Quickstart

Nilla provides a single entrypoint with a consistent structure for your Nix projects. In this guide we will learn how to install and run the Nilla CLI, add an input, and create a development shell.

Nilla CLI

To start working with Nilla projects we will need the Nilla CLI. This program makes it easier to do things like build packages, start development shells, etc. Install the Nilla CLI to get started.

# We can install the package imperatively.
nix profile install github:nilla-nix/cli

# Or we can run the Nilla CLI directly on-demand.
nix run github:nilla-nix/cli -- --help

# We'll install the Nilla CLI package for your system architecture.
system=$(nix-instantiate --eval --expr 'builtins.currentSystem' | tr -d '"')

# Install the package imperatively.
nix-env -iA packages.default.result.${system} https://github.com/nilla-nix/cli/archive/main.tar.gz

{
  description = "My Flake that contains my NixOS system configuration.";

  inputs = {
    nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";

    # Add the Nilla CLI as an input in your flake.
    nilla-cli.url = "github:nilla-nix/cli";
  };

  outputs = { nixpkgs, nilla-cli, ... }: {
    nixosConfigurations.myhost = nixpkgs.lib.nixosSystem {
      system = "x86_64-linux";

      modules = [
        ./configuration.nix
        ./hardware-configuration.nix

        # Add an additional module to your system configuration.
        ({ pkgs, ... }: {
          environment.systemPackages = [
            # Add the Nilla CLI to your system packages.
            nilla-cli.packages.${pkgs.system}
          ];
        })
      ];
    };
  };
}

{ pkgs, ... }:
let
  # Fetch and import the Nilla CLI.
  nilla-cli = import (pkgs.fetchFromGitHub {
    owner = "nilla-nix";
    repo = "cli";
    rev = "v0.0.0-alpha.8";
    # Try building with this empty hash first. Nix will let you
    # know what the correct hash to use is.
    sha256 = "0000000000000000000000000000000000000000000000000000";
  });
in
{
  # In your system configuration, add Nilla CLI to your system packages.
  environment.systemPackages = [
    nilla-cli.packages.default.result.${pkgs.system}
  ];
}

Create a new Nilla project

To start using Nilla, we need to create a nilla.nix file which contains a Nilla project. Let’s begin by using npins to fetch Nilla.

# Initialize npins
npins init --bare

# Pin Nilla
npins add github nilla-nix nilla

Now, we can make our nilla.nix file.

let
  # Import pinned inputs.
  pins = import ./npins;

  # Import Nilla.
  nilla = import pins.nilla;
in
  # Create our Nilla project.
  nilla.create {
    # Your project can be configured here.
  }

That is all we need to have a valid Nilla project!

Create a development shell

An empty project isn’t very useful. Let’s add Nixpkgs as an input and use it to create a development shell. To begin, we’ll use npins to fetch Nixpkgs.

# Pin Nixpkgs (you can use any channel you like)
npins add channel nixos-unstable

With Nixpkgs available in our pins, we can add it as an input and declare our shell.

let
  pins = import ./npins;

  nilla = import pins.nilla;
in
  nilla.create {
    config = {
      # Add Nixpkgs as an input (match the name you used when pinning).
      inputs.nixpkgs.src = pins.nixos-unstable;

      # With a package set defined, we can create a shell.
      shells.default = {
        # Declare what systems the shell can be used on.
        systems = [ "x86_64-linux" ];

        # Define our shell environment.
        shell = { mkShell, hello, ... }:
          mkShell {
            packages = [
              hello
            ];
          };
      };
    };
  }

Running the shell

Now that our development shell is defined in our project, we can use the Nilla CLI to start it.

nilla shell

To check that everything is working correctly, try running hello.

hello