Your First Flake

A Nix flake is a standardised way to define your project's dependencies, packages, and checks. If your project doesn't have a flake.nix yet, the easiest way to get started is to have an AI agent write one for you.

(Yes, experts will be able to write a better flake for you, but if you just want to try this out, this is the way to go.)

Step 1: Copy the prompt

Copy the following prompt and paste it into an AI coding agent. Run it from the root of your project.

# Nix Flake

Objective: Create a `flake.nix` for this project.


## Absolute Requirements

* `nix flake show --json --allow-import-from-derivation` succeeds
  without errors.
* `nix flake check` succeeds without errors.
* Every package is also a check, so that `nix flake check` builds
  every package.
* Every devShell is also a check, so that `nix flake check` builds
  every devShell.
* Support `x86_64-linux`.


## Nice to haves

- The default package builds the project.
- The default devShell contains all development
  dependencies.
- The project test suites are built somehow as part of
  `nix flake check`.


## Hints

* You can use `nix flake init` to create a basic flake.nix and
  then modify it to fit the requirements.
* Use the latest stable nixpkgs branch, for example: `nixos-25.11`.
  Check https://status.nixos.org for the current stable branch.
* Sometimes the latest stable nixpkgs branch does not have all the
  packages you need.
  That's a good example of when it's fine to use another nixpkgs
  branch.
* Avoid `flake-utils` and `flake-parts` for now.


## Tradeoffs

* It is more important that nix flake check passes than that the
  flake builds everything.
  I would rather have a flake with only a devShell than a flake
  that fails to `nix flake check`.
* Don't worry too much about eval warnings until after the
  requirements are met.
* Often tests can't "just" run as part of a nix build because
  they don't work inside the sandbox. Feel free to not run the tests
  in that case.


## Specific instructions

* Create a branch for this work, for example `your-first-flake`.
* Run `nix flake show --json --allow-import-from-derivation` and
  `nix flake check` after every edit to make sure you are on the
  right track.
* If either of those fail, fix the errors before making any other
  changes.
* Make many small commits, at least one after each time you got
  those commands to succeed. We can squash them later.

Step 2: Try it out

The agent will create a flake.nix file in your project root. Try it out by running:

nix flake check

If the command succeeds, your flake is ready. If it fails, ask the agent to fix the errors until it passes.

Step 3: Set up NixCI

Once nix flake check passes locally, you can set up NixCI to run it on every commit. See Getting Started to connect your repository.