nix-playgraound/notes/042-flake-apps.md

Flake Apps

This note covers 39-flake-apps/, which exposes runnable apps.<system> outputs instead of relying only on packages.

---

1. What an App Output Is

An app output is a small attrset with a type and a program path:

apps.${system}.default = {
  type = "app";
  program = "${reportPackage}/bin/show-rollout-report";
};

nix run looks for this schema. The program must already exist in the Nix store, so apps usually point at a package output.

---

2. Why This Example Still Defines Packages

The runnable programs are built with writeShellApplication, then exposed in two ways:

• packages.<system>.report and packages.<system>.promote build the scripts, and
• apps.<system>.default and apps.<system>.promote tell nix run which program to execute.

That separation keeps the build logic in packages and the command-line entry points in apps.

---

3. What the Example Demonstrates

This example keeps the data a little richer than a one-line hello script:

• one release train,
• three rollout waves, and
• one named app for the next promotion step.

That makes it clear that app outputs are just pointers to real programs. They do not replace packages or change how the program is built.

---

4. What the Check Verifies

nix flake check does not run apps automatically, so the example adds a check that executes both app program paths and verifies their output.

That is the pattern to remember: expose the app through apps, then add an explicit check if you want CI to prove the command works.

---

5. Commands to Try

cd 39-flake-apps

nix flake show
nix run
nix run .#promote
nix flake check