Clearer documentation around yarn install / --frozen-lockfile / --pure-lockfile

[redstubble]

Documentation is not clear when explaining installing yarn packages without editing the yarn.lock file. I am still confused between yarn install --frozen-lockfile and --pure-lockfile.

Currently

yarn install --pure-lockfile
Don’t generate a yarn.lock lockfile.

yarn install --frozen-lockfile
Don’t generate a yarn.lock lockfile and fail if an update is needed.

For both of these options there needs to be better documentation e.g.

If there is a yarn.lock file in the current directory, --frozen-lockfile and --pure-lockfile will use the exact versions from there instead of resolving them. This ensures that everyone using the library will get the same versions of the dependencies.

Only through much googling did I understand that yarn install was editing yarn.lock and these commands prevented it.

[dtgriscom]

A closely related problem is the lack of documentation on when the yarn.lock is generated and/or modified. There's the yarn.lock page, which says that the lock file is generated, and don't play with it; it doesn't say when/why it is generated or changed. Or, there's the yarn install page (referenced above), which only mentions yarn.lock in the situations where it won't be modified.

The yarn.lock page should clearly state when the yarn.lock file will or will not be generated. The yarn install page should clearly state the default behavior vis-à-vis generating or modifying yarn.lock.

This is probably the most important feature of yarn; it should be properly documented.

[DeeDeeG]

Also good to clarify: Is there ever a situation where --pure-lockfile and --frozen-lockfile will behave differently? (If so, what are the differences?)

As far as I can tell, --frozen-lockfile explicitly halts if the dependencies in yarn.lock can't be installed successfully. But what does --pure-lockfile do if the exact dependencies from yarn.lock can't be installed? It halts, right? If not... does it silently install packages based on the dependency ranges inpackage.json, without updating the lockfile?

This could definitely be clearer. And if they do the same thing, I propose saying one is an alias of the other. Otherwise, the distinction between them should be made more obvious.

[mojavelinux]

If not... does it silently install packages based on the dependency ranges inpackage.json, without updating the lockfile?

This is my observation, which seems to defeat the whole purpose of having a lock file. As far as I can discern, I don't think the lock file does anything useful because none of the available options do what we really want...which is to just install the versions listed in the lock file, don't fail, and don't touch the lock file. If there is such an option, I'd be very glad to learn about it.

[Telokis]

Do those options ressemble npm ci when used? I'm trying to get a similar behavior but I'm not sure if it fits.

[DeeDeeG]

So, here is what I have found, in practical terms. Tested with yarn 1.17.3.

• plain yarn install creates a lockfile (yarn.lock) if there isn't one yet.
  • yarn warns if there is a package-lock.json, but otherwise ignores package-lock.json
  • Updates individual dependencies in yarn.lock if package.json has been updated such that the version resolved in yarn.lock is out of the range required by package.json.
• --pure-lockfile checks if each dependency version that is resolved in yarn.lock is within the ranges required by package.json
  • If it is, install the version resolved in yarn.lock
  • If not, resolve the version range required by package.json and install that (no warning or error messages will be printed)
  • never modifies yarn.lock
• --frozen-lockfile checks if the whole yarn.lock file is a valid interpretation of package.json
  • If it is, install versions resolved in yarn.lock
  • If not, exit with an error

[Edit: A bunch of weird behavior I initially described here was due to copy-pasting garbled data. If anyone is still curious about that (now admittedly minor) issue, see: #7594 ]

[DeeDeeG]

@Telokis you probably want yarn install --frozen-lockfile

Having read the docs for npm ci, yarn install --frozen-lockfile is almost exactly the same. Although I don't think yarn install --frozen-lockfile will do this:

• If a node_modules is already present, it will be automatically removed before npm ci begins its install.

So I guess you may want to do:

rm -rf node_modules
yarn install --frozen-lockfile

Edit to add: yarn install --frozen-lockfile will happily run with no yarn.lock present. It only prints an info message:
info No lockfile found.

And otherwise proceeds as if there is no problem. This is unlike npm ci:

The project must have an existing package-lock.json or npm-shrinkwrap.json.

So if that is important to you, you can do

if [ -e yarn.lock ]; then
  rm -rf node_modules
  yarn install --frozen-lockfile
else
  false # This command exits with status 1 for "error"
  # alternatively, do this:
  # exit 1 # which may quit the CI script entirely, with exit status 1 for "error"
fi

[DeeDeeG]

Since this issue was opened, the following PR has landed to clarify the docs: yarnpkg/website#884

I think that does a pretty good job of explaining it.

The new text can be read here: https://yarnpkg.com/en/docs/cli/install#toc-yarn-install