FlakeHub best practices

At Determinate Systems, we believe that flakes are the future of Nix. But it’s not always clear how to use them to their full potential, so in this doc we’ll lay out some best practices for using flakes on FlakeHub based on both feedback from Determinate Systems customers as well our own experience as a company.

Use semantic versioning

On their own, flakes don’t have a concept of semantic versioning (SemVer). That’s because most current Nix users pull flakes, such as Nixpkgs, from source forges like GitHub. And since those source forges don’t have any concept of semantic versioning, at least when it comes to serving flake tarballs, Nix doesn’t have the requisite information to provide SemVer. Other sources for flakes, like the local filesystem, also don’t have the appropriate “hooks” that Nix would need to support SemVer.

FlakeHub, however, does provide SemVer for flakes and we recommend using it to full effect for the flakes that you publish. SemVer for flakes can apply not just to things like CLI tools and standard packages, but also to things like NixOS configurations. Why not publish version 1.4.0 of your authentication service or 0.2.5 of your main web application? You can even use Nix adoption as a reason to finally SemVer-ify parts of your stack that you hadn’t even considered.

With SemVer, your flake updates can become much smoother. Rather than updating a monolithic dependency like Nixpkgs every however-many months, you can make your updates more granular, handling any issues with discontinuity in gradual way.

Split things up into many flakes

The Nix community has generally gravitated toward a usage model that involves having few flake dependencies. We see this centralizing tendency in many corners and frequently encounter organizations that depend only on Nixpkgs in virtually all of their projects.

But we believe that things don’t need to be so centralized. Flakes are a great mechanism for grouping Nix expressions in granular ways and we built FlakeHub to make flakes “cheap”—cattle, not pets, if you will. We built the flakehub-push Action to make this trivial. In addition, you can put several flakes in a single repository, making this usage model friendly to large repos or even monorepos.

So just how many flakes do you need? There’s no hard-and-fast rule here, but in general we recommend publishing one flake per versioned thing, where a “thing” could be a versioned package like a CLI tool or NixOS configurations for a service or a series of Home Manager configurations or something else entirely.

When in doubt, create and publish another flake; you can always consolidate into larger flakes later if need be.

Update your inputs often

Keeping your flake inputs fresh can help make your updates smoother, which in turn can make the difference between fixing a series of small things incrementally over time, on one hand, and spending an afternoon trying to disentangle a mess where you’re not sure what is breaking what.

We have two tools that can help with this:

• Our Flake Checker Action helps you keep your Nixpkgs inputs up to date and either warns you or fails your CI runs if Nixpkgs is more than 30 days old (or a different number of days if you wish).
• Our update-flake-lock Action automatically updates your flake inputs on your preferred cron schedule and creates a pull request.

Follow the principle of least access

In larger organizations, we recommend a general policy of keeping your flakes private unless you absolutely need to distribute something to the broader Nix-using public. This ensures that only people inside your org can run operations like nix build or even nix flake show against those flakes.