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 with Nix modules, and have them reflected in flake schema values.

Features Flake definition aggregated from all flake-parts modules. Schema as options. Syntax for nixConfig and follows is the same as in flakes. flake check ensures files are up to date. App for generator: nix run .#write-flake Custom do-not-edit header. Automatic flake.lock flattening. Incrementally add flake-parts-builder templates. Pick flakeModules for different feature sets. Dendritic flake template.

this cute ouroboros is puking itself out.

• Who?
• What?
• Getting Started
• Usage
• Available Options
• About the Flake output function
• Automatic flake.lock flattening
• Migration Guide
• Development

• Nix users who want to keep their flake.nix modular 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 close to where their inputs are used. 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.nix with a single command whenever your options change.
• Flake as dependency manifest: Use flake.nix only for declaring dependencies, not for complex Nix code.
• Share and reuse modules: Teams can collaborate on 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               # check that 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               # check that flake.nix is up to date

The following is a complete example from our templates/dendritic template. It imports all modules from flake-file.flakeModules.dendritic.

{ inputs, lib, ... }:
{
  # That's it! Importing this module will add dendritic-setup inputs to your flake.
  imports = [ inputs.flake-file.flakeModules.dendritic ];
  # Define flake attributes on any flake-pars module:
  flake-file = {
    description = "My Awesome Flake";
    inputs.nixpkgs.url = lib.mkDefault "github:NixOS/nixpkgs/nixpkgs-unstable";
    inputs.nixpkgs-lib.follows = "nixpkgs";
  };
}

• Defines flake-file options.
• Exposes packages.write-flake.
• Exposes flake checks for generated files.

• Adds import-tree

• Includes flake-parts-builder's _bootstrap.nix.
• Uses bootstrap to load parts from ./flake-parts
• Uses bootstrap to load ./flake-parts/_meta as flake-file configs.

• Enables automatic flake.lock flattening using spikespaz/allfollow

• Enables automatic flake.lock flattening using fzakaria/nix-auto-follow

• Includes flakeModules.default.
• Includes flakeModules.import-tree.
• Includes flakeModules.allfollow.
• Adds flake-parts input.
• Enables flake.modules option used in dendritic setups.
• Sets output function to import-tree ./modules.
• Adds treefmt-nix input.
• Enables formatters: nixfmt, deadnix, and nixf-diagnose.

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;
}

A template for dendritic setups; includes flakeModules.dendritic.

A template that uses lib.flakeModules.flake-parts-builder.

Options use the same attributes as the flake schema. See below for details.

Example:

flake-file = {
  description = "my awesome flake";
  nixConfig = {}; # an attrset. currently not typed.
  inputs.<name>.url = "github:foo/bar";
  inputs.<name>.flake = false;
  inputs.<name>.inputs.nixpkgs.follows = "nixpkgs";
};

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 inputs

We 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 including a large Nix code string in it.

Tired of endlessly repeating tiny flake-parts modules or copy-pasting snippets between your projects? No more!

flake-parts-builder lets you incrementally add templated parts. This is much better than normal flake templates, since flake-parts templates can be added or removed at any time, not only at project initialization.

{ inputs, ... }: {
  imports = [
    (inputs.flake-file.lib.flakeModules.flake-parts-builder ./flake-parts)
  ];
}

nix run github:vic/flake-parts-builder/write-meta -- add --write-meta --parts systems,treefmt $PWD

You can add custom commands to be run whenever your flake.nix has been written or checked.

You can use the prune-lock options to specify a command that flake-file will use whenever your flake.nix file is generated to flatten your flake.lock dependency tree.

For flattening mechanisms we provide:

• flakeModules.allfollow that enables this using spikespaz/allfollow
• flakeModules.nix-auto-follow that enables this using fzakaria/nix-auto-follow

{ inputs, ... }:
{
  imports = [
    inputs.flake-file.flakeModules.allfollow
    # or optionally
    #inputs.flake-file.flakeModules.nix-auto-follow
  ];
}

This section outlines the recommended steps for adopting flake-file in your own repository.

1. Prerequisite: Ensure you have already adopted flake-parts.

2. Add Inputs: In your current flake.nix, add the following input:

   flake-file.url = "github:vic/flake-file";

3. Move Outputs: Copy the contents of your outputs function into a new file outputs.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 ...
   }

4. 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.
    };
    nixConfig = { }; # if you had any.
    description = "Your flake description";
  };
}

5. Backup: Back up your flake.nix into flake.nix.bak before regenerating it.
6. Generate: Execute nix run .#write-flake to generate flake.nix from inputs.nix.
7. Verify: Check flake.nix and if everything is okay, 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 handle it.

Use nix develop ./dev or with direnv: use flake ./dev.

[[general commands]]
  check - run flake check
  fmt   - format all files in repo
  menu  - prints this menu
  regen - regenerate all flake.nix files in this repo

• Found a bug or have a feature request? Open an issue.
• Contributions are welcome!

Made with <3 by @vic