flake-file lets you generate a clean, maintainable flake.nix from modular options, using flake-parts.
It makes your flake configuration modular and based on the Nix module system. This means you can use
lib.mkDefault or anything you normally do on Nix modules, and have them reflected on flake schema values.
|
|
- Who?
- What?
- Getting Started
- Usage
- Available Options
- About the Flake
outputfunction - Automatic flake.lock flattening
- Migration Guide
- Development
- Nix users who want to keep their
flake.nixmodular and maintainable - Anyone using flake-parts and looking to automate or simplify flake input management
- Teams or individuals who want to share and reuse flake modules across projects
flake-file lets you make your flake.nix dynamic and modular. Instead of maintaining a single, monolithic flake.nix, you define your flake inputs in separate modules near to their input use. flake-file then automatically generates a clean, up-to-date flake.nix for you.
- Keep your flake modular: Manage flake inputs just like the rest of your Nix configuration.
- Automatic updates: Regenerate your
flake.nixwith a single command whenever your options change. - Flake as dependency manifest: Use
flake.nixonly for declaring dependencies, not for complex Nix code. - Share and reuse modules: Teams can collaborate and share flake modules across projects including their dependencies.
Real-world examples: vic/vix uses flake-file. Our
dev/directory also uses flake-file to test this repo. More examples on GitHub.
To get started quickly, create a new flake based on our dendritic template:
nix flake init -t github:vic/flake-file#dendritic
nix flake check # checks flake.nix is up to date.
vim modules/default.nix # add another input.
nix run ".#write-flake" # regenerate flake
cat flake.nix # flake.nix built from your options.
nix flake check # checks flake.nix is up to date.See the Migration Guide if moving from an existing flake.
The following is a complete example from our templates/dendritic template. It imports all modules from flake-file.flakeModules.dendritic.
{ inputs, ... }:
{
# That's it! Importing this module will add dendritic-setup inputs to your flake.
imports = [ inputs.flake-file.flakeModules.dendritic ];
}- Defines
flake-fileoptions. - Exposes
packages.write-flake. - Exposes flake checks for generated files.
- Includes flakeModules.default.
- Adds
flake-partsinput. - Enables
flake.modulesoption used in dendritic setups. - Adds
import-treeinput. - Sets
outputfunction toimport-tree ./modules. - Adds
treefmt-nixinput. - Enables formatters:
nixfmt,deadnix, andnixf-diagnose. - Adds
allfollowinput. - Enables flake.lock automatic flattening.
A template for dendritic setups, includes flakeModules.dendritic.
A more basic, explicit setup.
# See templates/default
{ inputs, ... }: {
imports = [
inputs.flake-file.flakeModules.default
];
flake-file.inputs = {
flake-file.url = "github:vic/flake-file";
flake-parts.url = "github:hercules-ci/flake-parts";
nixpkgs.url = "github:nixos/nixpkgs/nixpkgs-unstable";
systems.url = "github:nix-systems/default";
};
systems = import inputs.systems;
}Use nix run .#write-flake to generate. (Tip: you can install it as a shell hook for your devshell.)
Options are similar to the flake schema, with a simplified follows syntax. See below for details.
| Option | Description |
|---|---|
flake-file.description |
Sets the flake description |
flake-file.nixConfig |
Attrset for flake-level nixConfig |
flake-file.inputs.<name>.url |
URL for a flake input |
flake-file.inputs.<name>.flake |
Boolean, is input a flake? |
flake-file.inputs.<name>.follows |
Map of dependencies to follow |
Example:
flake-file = {
description = "my awesome flake";
nixConfig = {}; # an attrset. currently not typed.
inputs.<name>.url = "github:foo/bar";
inputs.<name>.flake = false;
# This is the only difference from real flake schema.
# maps from `dependency-input` => `flake-input`.
inputs.<name>.follows.nixpkgs = "nixpkgs";
};Note: The
followssyntax is improved for clarity.Flake schema:
foo.inputs.bar.follows = "baz";flake-file syntax:
foo.follows.bar = "baz";This change makes it easier to reason about and maintain input dependencies.
See also, options.nix.
The flake-file.output option is a literal Nix expression. You cannot convert a Nix function value into a string for including in the generated flake file.
It defaults to:
inputs: import ./outputs.nix inputsWe recommend using this default, as it keeps your flake file focused on definitions of inputs and nixConfig. All Nix logic is moved to outputs.nix. Set this option only if you want to load another file with a Nix one-liner, but not for having a huge Nix code string in it.
Just add an allfollow input:
flake-file.inputs.allfollow.url = "github:spikespaz/allfollow";When allfollow is present in the flake.nix file,
nix run .#write-flake will automatically use allfollow to
flatten the flake.lock dependencies.
Flake check will also make sure dependencies are flat.
This section outlines recommended steps for adopting flake-file in your own repository.
-
Prerequisite: Ensure you have already adopted flake-parts.
-
Add Inputs: In your current
flake.nix, add the following two inputs:flake-file.url = "github:vic/flake-file";
-
Move Outputs: Copy the contents of your
outputsfunction into a new fileoutputs.nix:# outputs.nix -- copied the `outputs` value in here. inputs: inputs.flake-parts.lib.mkFlake { inherit inputs; } { imports = [ ./inputs.nix ]; # Add this for step 4. # ... all your existing modules ... }
-
Move Inputs: Copy your current flake.nix file as a flake-parts module (e.g.,
inputs.nix):# flake-file.nix -- copied from flake.nix and adapted as a flake-parts module. { inputs, ... }: { imports = [ inputs.flake-file.flakeModules.default # flake-file options. ]; flake-file = { inputs = { flake-file.url = "github:vic/flake-file"; # ... all your other flake inputs here. # # Update your dependencies follows from: # foo.inputs.bar.follows = "baz"; # into: # foo.follows.bar = "baz"; # }; nixConfig = { }; # if you had any. description = "Your flake description"; }; }
-
Backup: Backup your flake.nix into flake.nix.bak before re-generating it.
-
Generate: Execute
nix run .#write-flaketo generate flake.nix from inputs.nix. -
Verify: Check flake.nix and if everything is ok, remove the backup file.
You are done! Now you can move dependencies flake-file.inputs.foo from inputs.nix into any other imported module and nix run .#write-flake will take it.
# Run tests
nix flake check ./dev --override-input flake-file .
# Format
nix run ./dev#fmt
# Regenerate all flake.nix files in this repo.
nix run ./dev#regen- Found a bug or have a feature request? Open an issue.
- Contributions are welcome!
Made with <3 by @vic