https://github.com/stephank/yarn-plugin-nixify

Yarn v3/v4 plugin to help with Nix packaging
https://github.com/stephank/yarn-plugin-nixify

nix yarn

Last synced: 7 days ago
JSON representation

Yarn v3/v4 plugin to help with Nix packaging

• Host: GitHub
• URL: https://github.com/stephank/yarn-plugin-nixify
• Owner: stephank
• License: bsd-2-clause
• Created: 2020-08-23T16:14:15.000Z (over 4 years ago)
• Default Branch: main
• Last Pushed: 2024-12-11T07:59:10.000Z (about 1 month ago)
• Last Synced: 2025-01-09T02:40:58.979Z (14 days ago)
• Topics: nix, yarn
• Language: TypeScript
• Homepage:
• Size: 5.79 MB
• Stars: 68
• Watchers: 5
• Forks: 8
• Open Issues: 13
• Metadata Files:
  • Readme: README.md
  • License: LICENSE.md

Awesome Lists containing this project

README

        
# yarn-plugin-nixify

**Upgrading the plugin? See [UPGRADING.md](./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

  your `package.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.

[nix]: https://nixos.org

[yarn]: https://yarnpkg.com

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.

[node2nix]: https://github.com/svanderburg/node2nix

[yarn2nix]: https://github.com/nix-community/yarn2nix/

[composer-plugin-nixify]: https://github.com/stephank/composer-plugin-nixify

## Usage

This plugin is compatible with Yarn >= 3.1.0 or >= 4.0.0. Run the following in

your project folder to check:

```sh

# Check your Yarn version

yarn --version

# Upgrade to the latest version, if necessary

yarn set version berry

```

To then use the Nixify plugin:

```sh

# 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:

```nix

{ pkgs ? import  { } }:

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

  '';

})

```

## Settings

Some additional settings are available in `.yarnrc.yml`:

- `nixExprPath` can be set to customize the path where the Nixify plugin writes

  `yarn-project.nix`. For example, if you're also using [Niv] in your project,

  you may prefer to set this to `nix/yarn-project.nix`.

- `generateDefaultNix` can be set to `false` to disable generating a

  `default.nix`. This file is only generated if it doesn't exist yet, but this

  flag can be useful if you don't want a `default.nix` at all.

- `enableNixPreload` can be set to `false` to disable preloading Yarn cache

  into the Nix store. This preloading is intended to speed up a local

  `nix-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 to `true` 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](./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.

[niv]: https://github.com/nmattia/niv

## Hacking

```sh

# 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.)