What does yarn --prefer-offline do?

Question

I assume when I install npm package say react for the first time with

yarn add react

this will save react file in local cache. I found .yarn-cache to contain many files. I assume it is yarn local cache folder so that when I install react again in the future, it will be installed from local cache, no??

If I need to install react again in the future, should I simply write this:

yarn add react

or this:

yarn add react --prefer-offline

Answer 1

My understanding is that by default, yarn will always try to download the package from the internet when you install/restore it, and will also store that in the cache, which means that in the future if you try to install/restore and don't have an internet connection, it can fall back on the cache and install from there if necessary. By specifying --prefer-offline, you are reversing this behaviour so that it will check the cache first, and only try to download the package from the internet if it cannot find it in the cache. This can make your install/restores significantly quicker, and will allow you perform repeatable builds, but you may not get the latest versions available (e.g. if you're using version specs like ~1.2.3). There is also an --offline option, which will throw an error if it can't find a package in your local cache (i.e. it won't ever try to download from the internet).

More info at https://yarnpkg.com/blog/2016/11/24/offline-mirror/

Answer 2

In order to use --prefer-offline you first have to setup your offline package repo.

Let's setup our cache in a hidden dir in the home folder:

yarn config set yarn-offline-mirror ./.npm-offline  

Also set a config to have yarn clean the dowloaded tarballs:

yarn config set yarn-offline-mirror-pruning true

Now, whenever you run yarn install in some project, it will cache the modules in this directory, available for you to then fetch using yarn --prefer-offline.

When you want to later, perhaps in a new project, install from the cache you will need to specify the desired module version as it doesn't have a concept of latest. Easiest is to simply try to add:

yarn add moment

On my machine this prints:

error Couldn't find any versions for "moment" that matches "latest" in our cache. 
Possible versions: "2.1.0, 2.13.0, 2.17.0, 2.17.1, 2.18.1, 2.19.1, 2.19.2, 2.19.3, 2.8.4" 
// Note that above is not in semver order...

I can then install latest offline with:

yarn add [email protected]

The Yarn blog post mentioned by @adrian elaborates on how to a per project cache and how to commit that for your team if desired. I myself use just one cache for in order to be ideally able to bootstrap new projects while offline.