4. Build a package using Nix

While Nix can do many things, package management is the thing that it's perhaps best known for. In this tutorial, we'll use our installed Nix CLI to build and run some Nix packages included in Nixpkgs. Later in the guide we'll build and run a Nix package defined in a local flake.

Build a package from Nixpkgs

Let's start by building bat, a syntax-highlighted version of cat written in Rust that has a Nix package defined in Nixpkgs, in an empty directory (make sure to run this in a directory where you have write access):

mkdir build-nix-package && cd build-nix-package
nix build "nixpkgs#bat"

Here, nixpkgs is a flake reference to the NixOS/nixpkgs repository on GitHub, while #bat indicates that we're building the bat output from the Nixpkgs flake.

When the build is done, run ls . and you should see something called result in the current directory. result is actually a symlink to the built package in the Nix store, which you can verify:

readlink result

You should see a path like this (it's likely to be a bit different on your machine):

        

          
            /nix/store/
          
          
            1. Nix store prefix
          
        
        

          
            sglc12hc6pc68w5ppn2k56n6jcpaci16
          
          
            2. Hash part
          
        
        -
        

          bat-0.22.1
          
            3. Package name
          
        
        
        
      

What's happened here is that the Nix CLI has:

• Downloaded the Nix code in Nixpkgs
• Found a package definition with the name bat (code here)
• Used the build instructions for bat to build the package
• Stored the result in the Nix store using Nix's hash-based path system

You can now run bat:

./result/bin/bat --help

🚀 Success! You've built and run a package using Nix.

Build a package for tools written in $LANGUAGE

One of the great things about Nix is that package builds are extremely flexible, which enables you to create packages for things written in just about any programming language. In this section, we'll explore that by building and running packages for tools written in a variety of languages. Select one below to see some examples:

nix build "nixpkgs#nodePackages.npm"
./result/bin/npm --help

Beyond Nixpkgs

While Nixpkgs is by far the largest Nix package repository in the known universe, any Nix flake can include package outputs. Let's build a package from a different repo, this time the package for Home Manager, a popular Nix tool for configuring home environments:

nix build "github:nix-community/home-manager"

Here, github:nix-community/home-manager is a flake reference to the nix-community/home-manager repo on GitHub. To run Home Manager:

./result/bin/home-manager --help

Upstreaming your packages to Nixpkgs is always an option, but it's good to bear in mind that with Nix you can distribute packages via any public Git repository with a flake.nix.

Build a package in a local flake

Earlier in this guide, we built a Nix package defined in Nixpkgs to get a sense of some of the mechanics of that process. In this guide, we'll dig a bit deeper and build a Nix package defined in a local Nix flake.

As above, select a preferred language:

To get started in your JavaScript project, create an empty directory and initialize a flake template:

mkdir nix-javascript-pkg && cd nix-javascript-pkg
nix flake init --template "github:DeterminateSystems/zero-to-nix#javascript-pkg"

Whichever language you've selected, you can build the Nix package defined in the local flake by running:

nix build

This command determines that the local flake has a package output that defines how the package is built. In this particular flake there's a default package, which enables us to run nix build without specifying an output, but if the package were output as packages.mypkg, for example, we'd need to run nix build .#mypkg to build it.

flake.nix{
  packages.default = pkgs.buildNpmPackage {
    name = "zero-to-nix-javascript";

    # The packages required by the build process
    buildInputs = [
      pkgs.nodejs_18
    ];

    # The code sources for the package
    src = ./.;
    npmDepsHash = "sha256-Ghh9jxxJH7lgn99X1L6WAhrsQhnJlub2cyUUBmSBwfQ=";

    # How the output of the build phase
    installPhase = ''
      mkdir $out
      npm run build
      cp dist/index.html $out
    '';
  }
}

We won't delve too much deeper into derivations and creating your own packages here, but we hope that this guide shows you how Nix code gets turned into real build output.