yarnpkg / website

Yarn package manager website

Yarn Website

This repo contains the source code for the Yarn Classic (v1) website, available at https://classic.yarnpkg.com/. For the Yarn v2 site, see https://github.com/yarnpkg/berry/tree/master/packages/docusaurus

README in Japanese

In order to get started:

$ git clone [email protected]:yarnpkg/website.git yarn-website
$ cd yarn-website

You should ensure you have Yarn and Bundler installed:

$ gem install bundler

And then:

$ make

Or:

$ make install
$ make serve

On Windows, make is not available, so you need to execute bundle and jekyll directly:

bundle install
bundle exec jekyll serve --incremental

---

Special thanks to Netlify for powering the website.

website's Issues

How Yarn Works

Under: en/docs/how-yarn-works

Do we need this for the initial launch? I think linking to the announcement blog post is enough for now; it tells the story.

Contributing page

Would be good to put on the site since it can be translated.

Starting point: https://github.com/yarnpkg/yarn/blob/master/CONTRIBUTING.md

Add docs for "flat" package.json field

I didn't see the "flat" option mentioned here: https://yarnpkg.com/en/docs/package-json or https://yarnpkg.com/en/docs/creating-a-package

The flat option in package.json was added here: yarnpkg/yarn@06e81aa

There are two main points to cover: flat: true in the top level package.json triggers a flat installation. flat: true in a dependency throws if it's installed in a non-flat installation.

yarn generate-lock-entry

Detect operating system and show relevant setup instructions

It would be nice to detect the user's operating system (probably based on user-agent) and display the correct installation instructions. For example, apt-get on Debian or Ubuntu, link to msi file or Chocolately instructions for Windows, etc.

See Atom's site for an example of this: https://atom.io/

yarn bin

behaves just as npm bin.

This doesn't have a docs entry yet at all as I just added the command.

yarn cache

Depends on yarnpkg/yarn#529

yarn access

depends on yarnpkg/yarn#377.

yarn licenses ls

Depends on yarnpkg/yarn#530

CLI Introduction

Under: en/docs/cli/

This should say a little bit about the CLI and tell which commands are most important or something.

Permission denied on make command

make install
Cloning into '/Users/ilen/Desktop/openSource/yarn-website/_sass/bootstrap'...
Permission denied (publickey).
fatal: Could not read from remote repository.
Please make sure you have the correct access rights
and the repository exists.

i m getting this error on executing make command
What is public key?

Governance page

Would be good to put on the site since it can be translated.

Blocked by: yarnpkg/yarn#274

Migrating from Bower guide

Site should have og:graph meta tag

Currently it looks pretty bad when shared on Facebook - There's no image.

https://developers.facebook.com/tools/debug/sharing/?q=https%3A%2F%2Fyarnpkg.com%2F

Compatibilty with npm page

yarnpkg/yarn#375

Release process page

Would be good to put on the site since it can be translated.

Blocked by: yarnpkg/yarn#376

yarn install --har

har har har

yarnpkg/yarn#536

Add some performance results to the documentation / website

These are the times to install React Native's dependencies on my computer. The full results are below and I've also grouped some of them by common use cases based on npm and kpm's default choice of whether to make a lockfile.

I'm excited about all of the results; kpm is always faster. One thing that's great is that when package.json hasn't changed in a project you're actively working on, kpm runs in under a second.

Scenario: You've cloned a project for the first time

Cold cache, no node_modules

npm w/out shrinkwrap
real    2m30.195s
user    0m42.299s
sys 0m13.304s

kpm w/lockfile
real    0m22.794s
user    0m21.280s
sys 0m13.261s

Warm cache, no node_modules

npm w/out shrinkwrap
real    1m52.698s
user    0m38.867s
sys 0m12.251s

kpm w/lockfile
real    0m9.359s
user    0m8.287s
sys 0m6.456s

Scenario: You've pulled new commits to a project you're working on

Warm cache, node_modules populated

npm w/out shrinkwrap
real    0m4.189s
user    0m4.182s
sys 0m0.284s

kpm w/lockfile
real    0m0.710s
user    0m0.515s
sys 0m0.090s

In practice, these times will be higher when there are changes to package.json. But when there aren't any changes to package.json since the last time you installed dependencies, kpm is very fast.

npm times

npm, cold cache, w/out node_modules, w/out shrinkwrap
real    2m30.195s
user    0m42.299s
sys 0m13.304s

npm, cold cache, w/out node_modules, w/shrinkwrap
real    0m52.358s
user    0m39.970s
sys 0m18.146s

npm, warm cache, w/out node_modules, w/shrinkwrap
real    0m52.851s
user    0m41.047s
sys 0m17.901s

npm, warm cache, w/out node_modules, w/out shrinkwrap
real    1m52.698s
user    0m38.867s
sys 0m12.251s

npm, warm cache, w/node_modules, w/shrinkwrap
real    0m5.285s
user    0m5.289s
sys 0m0.315s

npm, warm cache, w/node_modules, w/out shrinkwrap
real    0m4.189s
user    0m4.182s
sys 0m0.284s

kpm times

kpm, cold cache, w/out node_modules w/out lockfile
real    0m15.028s
user    0m11.915s
sys 0m8.327s

kpm, cold cache, w/out node_modules, w/lockfile
real    0m22.794s
user    0m21.280s
sys 0m13.261s

kpm, warm cache, w/out node_modules, w/lockfile
real    0m9.359s
user    0m8.287s
sys 0m6.456s

kpm, warm cache, w/out node_modules, w/out lockfile
real    0m14.563s
user    0m12.130s
sys 0m8.496s

kpm, warm cache, w/node_modules, w/out lockfile
real    0m7.564s
user    0m6.055s
sys 0m1.331s

kpm, warm cache, w/node_modules, w/lockfile
real    0m0.710s
user    0m0.515s
sys 0m0.090s

Missing navigation

Hi!

When following the website docs this page https://yarnpkg.com/en/docs/cli/generate-lock-entry does not have the bottom navigation, others page do

yarn clean

Add table mapping npm commands to yarn commands

Something like:

npm	yarn
npm install	yarn install
npm install [package]	_(Intentionally not supported)_
npm install --save [package]	yarn add [package]
npm install --save-dev [package]	yarn add --dev [package]
...	...

jQuery & Bootstrap

Do we really need to use jQuery and Bootstrap in the site?

Documentation

Over the weekend I built out most of the Yarn website and it's now ready for a push to fill out the documentation.

We have a bunch of people working on the documentation in a war room in 14.03 by the walkway to building 12, on September 27-28, so come by if you'd like to help!

TODO

Here are all the pages of documentation needed before publish. Everything is broken down into "guides". The guides are each accessible from the /en/docs/ page.

• Getting Started
  • Getting Started (@thejameskyle)
  • Installation (@thejameskyle)
  • Usage (@thejameskyle)
• The Yarn Workflow (see #37)
  • Creating a package.json (including common things) (@JoelMarcey)
  • Installing dependencies (@JoelMarcey)
  • Running scripts (@JoelMarcey)
  • Updating dependencies (including details on lockfile) (@JoelMarcey)
• CLI Commands
  • Intro (not taken)
  • yarn access (not taken) -- not implemented yet
  • yarn add (@lacker)
  • yarn cache (not taken) -- not implemented yet
  • yarn check (@ericnakagawa)
  • yarn clean (@ericnakagawa)
  • yarn config (not taken) (some functionality on missing-commands branch)
  • yarn dist-tag (@thejameskyle)
  • yarn global (not taken)
  • yarn info (@jamesgpearce, #28)
  • yarn init (not taken)
  • yarn install (@thejameskyle)
  • yarn licenses (@thejameskyle)
  • yarn link (not taken) -- couldn't test, may be unimplemented yarnpkg/yarn#336
  • yarn login (@thejameskyle)
  • yarn logout (@thejameskyle)
  • yarn ls (@thejameskyle)
  • yarn outdated (@ericnakagawa) (on missing-commands branch)
  • yarn owner (@lacker)
  • yarn pack (@ericnakagawa)
  • yarn publish (@lacker)
  • yarn run (not taken) -- the set of scripts is not finalized
  • yarn self-update (not taken) -- on hold until 'config' added
  • yarn team (not taken) -- no code yet, need to review PR
  • yarn uninstall (@lacker)
  • yarn unlink (not taken)
  • yarn upgrade (@caabernathy) --waiting on this issue resolution yarnpkg/yarn#458
  • yarn version (@jamesgpearce, #46)
  • yarn why (@jamesgpearce, #43)
• Configuring Yarn (still needs a placeholder)
  • The package.json format (@ericvicenti)
  • The yarn.lock format (@ericvicenti)
  • Folders? (not taken)
• Migrating from npm
  • Migrating from npm (@lacker)
    • Include info about shrinkwraps (yarnpkg/yarn#397)
• Creating a Package
  • Creating a package (@JoelMarcey) (see #29)
  • Preparing a package for publish (@JoelMarcey) (see #40)
  • Publishing a package (@JoelMarcey) (see #42)
• How Yarn Works
  • How Yarn Works (not taken)
• The Yarn Organization (@thejameskyle)

Misc Tasks

• Go through again and update documentation to include details about alternative registries
• Review documentation for

Many of these line up with documents on the npm docs website: https://docs.npmjs.com/, please don't just copy and paste them. There are a number of things that are different in Yarn, things that haven't been implemented yet, things that npm has for legacy reasons, etc.

When writing documentation, make sure that you're writing them for a reader that has never used npm before. Don't require prior knowledge about how npm works and don't send people off to the npm documentation unless you're discussing interop with npm directly.

---

Tips

I wrote up a guide on (what I think are) best practices when writing documentation: https://github.com/thejameskyle/documentation-handbook

Remember that you must follow the Yarn Code of Conduct: https://github.com/yarnpkg/yarn/blob/master/CODE_OF_CONDUCT.md (Contributor's Covenant)

---

Before you go

If you want to take one or more of these docs on please update the issue with your @username so others know you're working on it.

yarn global

"yarn global add " replaces "npm install -g ".

Working with Version Control

en/docs/version-control

yarn self-update

yarn clean

@kittens, can you explain what 'yarn clean' is meant to do?

After reviewing the code a list of files (ignoreFiles) ends up getting removed (await fs.unlink(loc);).

Are these files not supposed to be deleted?

Link to documentation of 'yarn clean' as it currently works: #22

yarn ls <package>

Depends on yarnpkg/yarn#531

Page on npm registry features

It would be good to have a page that documents that people who are using npm enterprise and private packages can still use Yarn for the client

Using package.json

Under en/docs/configuration/package-json

Redirect for latest download / Download permalinks

Would be nice to be able to do something like wget https://yarnpkg.com/latest.tar.gz to get the latest tarball. Server should do a 302 (temporary) redirect to the latest download URL, which I assume we'd continue hosting using Github releases (for example, https://github.com/yarnpkg/yarn/releases/download/v0.13.5/kpm-v0.13.5.tar.gz)

Also ideal would be something like https://yarnpkg.com/releases/0.13.5.tar.gz to download one particular version, so as to not tightly-couple the URL scheme to Github.

Dependencies and versions

Lives under en/docs/dependencies

Drop shadow

Can we drop the drop shadow and heavy font on the homepage? I think it looks a bit dated.

eg A lighter unshadowed font:

yarn run

yarn link

yarn upgrade

yarn init

need `sudo` permission to write tarball file, if as usual user on macOS

I think the command of the document need sudo

And Yarn is now in /opt/dist/ not /opt/yarn-[version]/ after tar zvxf yarn-*.tar.gz

yarn version

yarn outdated <package>

Depends on yarnpkg/yarn#532

Document .yarnrc, how to use @scoped private packages, how to configure multiple registries

Docs are super sparse/non-existent on how to use yarn with the above.

Moved from yarnpkg/yarn#689.

Spanish translations!

Hi!

I will start translating the docs to Spanish!

Stay tuned :D

yarn team

Depends on yarnpkg/yarn#377

Debian installation fails because of existing virtual package

On debian, there's already a virtual package named yarn which installs cmdtest package.

From the cmdtest package description:

Also included is a "scenario testing" tool, yarn.

That yarn has nothing to do with this one, but it prevents this one from getting installed.

% lsb_release -a
No LSB modules are available.
Distributor ID: Debian
Description:    Debian GNU/Linux unstable (sid)
Release:    unstable
Codename:   sid

% apt-cache showpkg yarn
Package: yarn
Versions: 

Reverse Depends: 
Dependencies: 
Provides: 
Reverse Provides: 
cmdtest 0.27-1 (= )

Code of Conduct page

https://github.com/yarnpkg/yarn/blob/master/CODE_OF_CONDUCT.md

Translations

Under: en/org/translations

<title> of every page is “Yarn”

Would be helpful to have the <title> match the title of the page.

Installing Dependencies

This is in en/docs/installing-dependencies

Users page

yarn config