Upgrading the plugin? See UPGRADING.md
Generates a Nix expression to build a Yarn v3 or v4 project (not using zero-install).
-
Provides a
yarn
shell alias in the Nix builder — no global Yarn v1 install needed. -
A default configure-phase that runs
yarn
in your project. (May be all that's needed for plain JavaScript projects.) -
A default install-phase that creates executables for you based on
"bin"
in yourpackage.json
, making your package readily installable. -
Preloading of your Yarn cache into the Nix store, speeding up local
nix-build
. -
Automatically keeps your Nix expression up-to-date as you
yarn add
/yarn remove
dependencies. -
No Nix installation required for the plugin itself, so it should be safe to add to your project even if some developers don't use Nix.
Related projects:
-
node2nix, yarn2nix: Both do a similar job, but as separate commands. By comparison, this plugin tries to automate the process and make things easy for Nix and non-Nix devs alike.
-
composer-plugin-nixify: Similar solution for PHP with Composer.
This plugin is compatible with Yarn >= 3.1.0 or >= 4.0.0. Run the following in your project folder to check:
# Check your Yarn version
yarn --version
# Upgrade to the latest version, if necessary
yarn set version berry
To then use the Nixify plugin:
# Install the plugin
yarn plugin import https://raw.githubusercontent.com/stephank/yarn-plugin-nixify/main/dist/yarn-plugin-nixify.js
# Run Yarn as usual
yarn
# Build your project with Nix
nix-build
Running yarn
with this plugin enabled will generate two files:
-
yarn-project.nix
: This file is always overwritten, and contains a basic derivation for your project. -
default.nix
: Only generated if it does not exist yet. This file is intended to be customized with any project-specific logic you need.
This may already build successfully! But if your project needs extra build
steps or native dependencies, you may have to customize default.nix
a bit.
Some examples of what's possible:
{ pkgs ? import <nixpkgs> { } }:
let
project = pkgs.callPackage ./yarn-project.nix {
# Example of selecting a specific version of Node.js.
nodejs = pkgs.nodejs-14_x;
} {
# Example of providing a different source tree.
src = pkgs.lib.cleanSource ./.;
};
in project.overrideAttrs (oldAttrs: {
# If your top-level package.json doesn't set a name, you can set one here.
name = "myproject";
# Example of adding packages to the build environment.
# Especially dependencies with native modules may need a Python installation.
buildInputs = oldAttrs.buildInputs ++ [ pkgs.python3 ];
# Example of invoking a build step in your project.
buildPhase = ''
yarn build
'';
})
Some additional settings are available in .yarnrc.yml
:
-
nixExprPath
can be set to customize the path where the Nixify plugin writesyarn-project.nix
. For example, if you're also using Niv in your project, you may prefer to set this tonix/yarn-project.nix
. -
generateDefaultNix
can be set tofalse
to disable generating adefault.nix
. This file is only generated if it doesn't exist yet, but this flag can be useful if you don't want adefault.nix
at all. -
enableNixPreload
can be set tofalse
to disable preloading Yarn cache into the Nix store. This preloading is intended to speed up a localnix-build
, because Nix will not have to download dependencies again. Preloading does mean another copy of dependencies on disk, even if you don't do local Nix builds, but the size is usually not an issue on modern disks. -
individualNixPackaging
can be set totrue
to create a derivation per dependency. This is useful in some cases, but can significantly slow down builds if cache is cold and preloading is not possible. -
isolatedNixBuilds
, see ISOLATED_BUILDS.md. -
installNixBinariesForDependencies
can be set to also install executables for binaries defined by dependencies. This can be useful if these need to be in$PATH
for other tools, or if you're creating a workspace just to collect command-line tools.
# In this directory:
yarn
yarn build-dev
# In your test project:
yarn plugin import /path/to/yarn-plugin-nixify/dist/yarn-plugin-nixify.dev.js
(Alternatively, add a direct reference in .yarnrc.yml
. This will likely only
work if the Nix sandbox is disabled.)