Configuring an Offline Mirror with Yarn for reliable builds

What is an offline Mirror

It is very important for large JavaScript projects to have repeatable and reliable builds. If the builds that our project depends on are downloaded from network, this build system is neither reliable nor is it repeatable.

An important advantage of Yarn is that it can install node_modules from files that are located in your file system. These files are known as Offline Mirror, this is because it mirrors the files that are downloaded from the registry during the first build and stores them locally for future builds.

The offline mirror differs from both yarn and npm CLI cache. A cache stores already unzipped tarball that is downloaded from the registry, the cache can also be implementation specific and could even be invalid between multiple versions of CLI tools. On the other hand, the tarballs in ?offline mirror? can be consumed by any version of Yarn that will build cache based on them.

why do we need an offline mirror?

When you run yarn install, the yarn.lock file will have sections for dependencies, these dependencies have a resolved field with a remote URL. When you delete the node_modules file and run yarn install again, yarn downloads the same resolved dependencies that are specified in this lockfile. However, if these urls are unreachable during your build, the installation will fail. You use the offline mirror to solve this problem.

Set up .yarnrc

To get started with yarn offline mirror, you will have to set up a .yarnrc file, you do this using the yarn config command, here is an example:

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

The ./npm-package-offline-cache defines the relative location to your home folder where all the source.tar.gz files are downloaded to the registry.

An offline mirror does not come with removing tarballs. To keep the cache folder updated, you have to add the following to the config file:

yarn config set yarn-offline-mirror-pruning true

This creates a .yarnrc file in your HOME directory. Now you have to move this file to the project root so that the mirror would be used only for this project.

mv ~/ .yarnrc ./

initialize the new lockfile

Now you have to remove the node_modules folder that was previously generated and run yarn install again:

rm -rf node_modules/ yarn.lock```
```yarn install

The offline cache will be located in the npm-packages-offline-cache folder that you configured earlier. If you list the files in this folder, it will contain the files yarn uses for the following builds without reaching out to network:

ls npm-packages-offline-cache/

Note if you are using windows, you will need to use dir command on the command line instead of ls.

Testing

To ensure that it is offline, you will have to do this:

• Clear your global cache using "yarn cache clean"
• Disconnect from network.
• Then run "yarn install -offline". The offline flag will ensure yarn does not reach out to the network

Previous: Understanding and Managing the yarn.lock configuration file.
Next: Pruning an Offline Mirror in Yarn for optimized builds.