oeiuwq.com
Generate flake.nix from module options. Discussions: https://oeiuwq.zulipchat.com/join/nqp26cd4kngon6mo3ncgnuap/
dendrix.oeiuwq.com/Dendritic.html
dendritic
nix
inputs
readme
+10
-399
+10
-399
README.md
+10
-399
README.md
···
13
13
14
14
> `flake-file` and [vic](https://bsky.app/profile/oeiuwq.bsky.social)'s [dendritic libs](https://vic.github.io/dendrix/Dendritic-Ecosystem.html#vics-dendritic-libraries) made for you with Love++ and AI--. If you like my work, consider [sponsoring](https://github.com/sponsors/vic)
15
15
16
-
**flake-file** lets you generate a clean, maintainable `flake.nix` from modular options. Use the _real_ Nix language to define your inputs.
16
+
**flake-file** lets you generate a clean, maintainable `flake.nix` from Nix module options. Use the _real_ Nix language to define your inputs.
17
+
18
+
It makes your flake definition base on the Nix module system.
19
+
20
+
This means
17
21
18
-
It makes your flake configuration modular and based on the Nix module system. This means you can use
19
-
`lib.mkDefault` or anything you normally do with Nix modules, and have them reflected in flake schema values.
22
+
- You can use `lib.mkDefault` or anything you normally do with the Nix language, and have them reflected in flake.nix.
23
+
- Your inputs follow a **typed Input Schema**.
24
+
- Your outputs can be defined on a **typed Output Schema**.
20
25
21
26
> Despite the original flake-oriented name, it NOW also works on _stable Nix_, non-flakes environments via [npins](templates/npins) or [unflake](templates/unflake).
22
27
···
25
30
## Features
26
31
27
32
- Flake definition aggregated from Nix modules.
28
-
- Schema as [options](https://github.com/vic/flake-file/blob/main/modules/options/default.nix).
33
+
- [Input](https://github.com/vic/flake-file/blob/main/modules/options/default.nix) and Output schemas based on Nix types.
29
34
- Syntax for nixConfig and follows is the same as in flakes.
30
35
- `flake check` ensures files are up to date.
31
36
- App for `flake.nix` generator: `nix run .#write-flake`
···
44
49
45
50
</td></tr></table>
46
51
47
-
---
48
-
49
-
## Table of Contents
50
-
51
-
- [Who?](#who-is-this-for)
52
-
- [What?](#what-is-flake-file)
53
-
- [Getting Started](#getting-started-try-it-now)
54
-
- [Usage](#usage)
55
-
- [Available Options](#available-options)
56
-
- [About the Flake `output` function](#about-the-flake-output-function)
57
-
- [Automatic flake.lock flattening](#automatic-flakelock-flattening)
58
-
- [Migration Guide](#migration-guide)
59
-
- [Development](#development)
60
52
61
-
---
62
-
63
-
## Who is this for?
64
-
65
-
- Nix users who want to keep their `flake.nix` modular and maintainable
66
-
- Anyone using Nix modules and looking to automate or simplify flake input management
67
-
- Teams or individuals who want to share and reuse flake modules **across projects** even if some use flakes and others npins.
68
-
69
-
---
70
-
71
-
## What is flake-file?
72
-
73
-
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.
74
-
75
-
- **Keep your flake modular:** Manage flake inputs just like the rest of your Nix configuration.
76
-
- **Automatic updates:** Regenerate your `flake.nix` with a single command whenever your options change.
77
-
- **Flake as dependency manifest:** Use `flake.nix` only for declaring dependencies, not for complex Nix code.
78
-
- **Share and reuse modules:** Teams can collaborate on and share flake modules across projects, including their dependencies.
79
-
80
-
> Real-world examples: [vic/vix](https://github.com/vic/vix) uses flake-file. Our [`dev/`](https://github.com/vic/flake-file/blob/main/dev) directory also uses flake-file to test this repo. [More examples on GitHub](https://github.com/search?q=%22vic%2Fflake-file%22+language%3ANix&type=code).
81
-
82
-
---
83
-
84
-
## Getting Started (try it now!)
85
-
86
-
To get started quickly, create a new flake based on our [dendritic](https://github.com/vic/flake-file/tree/main/templates/dendritic) template:
87
-
88
-
```shell
89
-
nix flake init -t github:vic/flake-file#dendritic
90
-
nix run ".#write-flake" # regenerate flake.nix and flake.lock
91
-
cat flake.nix # flake.nix built from your options
92
-
nix flake check # check that flake.nix is up to date
93
-
```
94
-
95
-
> [!TIP]
96
-
> See the [Migration Guide](#migration-guide) if you're moving from an existing flake.
97
-
98
-
---
99
-
100
-
## Usage
101
-
102
-
The following is a complete example from our [`templates/dendritic`](https://github.com/vic/flake-file/blob/main/templates/dendritic) template. It imports all modules from [`flake-file.flakeModules.dendritic`](https://github.com/vic/flake-file/tree/main/modules/dendritic).
103
-
104
-
```nix
105
-
{ inputs, lib, ... }:
106
-
{
107
-
# That's it! Importing this module will add dendritic-setup inputs to your flake.
108
-
imports = [ inputs.flake-file.flakeModules.dendritic ];
109
-
110
-
# Define flake attributes on any flake-parts module:
111
-
flake-file = {
112
-
description = "My Awesome Flake";
113
-
inputs.nixpkgs.url = lib.mkDefault "github:NixOS/nixpkgs/nixpkgs-unstable";
114
-
inputs.nixpkgs-lib.follows = "nixpkgs";
115
-
};
116
-
}
117
-
```
118
-
119
-
### Available flakeModules
120
-
121
-
#### [`flakeModules.default`](https://github.com/vic/flake-file/tree/main/modules/default.nix)
122
-
123
-
- Defines `flake-file` options.
124
-
- Exposes `packages.write-flake`.
125
-
- Exposes flake checks for generated files.
126
-
127
-
#### [`flakeModules.import-tree`](https://github.com/vic/flake-file/tree/main/modules/import-tree.nix)
128
-
129
-
- Adds [import-tree](https://github.com/vic/import-tree)
130
-
131
-
#### [`lib.flakeModules.flake-parts-builder`](https://github.com/vic/flake-file/tree/main/modules/flake-parts-builder/default.nix)
132
-
133
-
- Includes flake-parts-builder's `_bootstrap.nix`.
134
-
- Uses bootstrap to load parts from ./flake-parts
135
-
- Uses bootstrap to load ./flake-parts/\_meta as flake-file configs.
136
-
137
-
#### [`flakeModules.allfollow`](https://github.com/vic/flake-file/tree/main/modules/prune-lock/allfollow.nix)
138
-
139
-
- Enables [automatic flake.lock flattening](#automatic-flakelock-flattening) using [spikespaz/allfollow](https://github.com/spikespaz/allfollow)
140
-
141
-
#### [`flakeModules.nix-auto-follow`](https://github.com/vic/flake-file/tree/main/modules/prune-lock/nix-auto-follow.nix)
142
-
143
-
- Enables [automatic flake.lock flattening](#automatic-flakelock-flattening) using [fzakaria/nix-auto-follow](https://github.com/fzakaria/nix-auto-follow)
144
-
145
-
#### [`flakeModules.dendritic`](https://github.com/vic/flake-file/tree/main/modules/dendritic/default.nix)
146
-
147
-
- Includes flakeModules.default.
148
-
- Includes flakeModules.import-tree.
149
-
- Enables [`flake-parts`](https://github.com/hercules-ci/flake-parts).
150
-
- Sets `outputs` to `inputs: inputs.flake-parts.lib.mkFlake { inherit inputs; } (inputs.import-tree ./modules)`.
151
-
152
-
> Previously, this module included `flake-aspects` and `den` as dependencies. It now provides a pure flake-parts Dendritic setup. If you need the complete [den](https://github.com/vic/den) functionality, use den's `flakeModules.dendritic` instead.
153
-
154
-
#### [`flakeModules.npins`](https://github.com/vic/flake-file/tree/main/modules/npins.nix)
155
-
156
-
- Defines `flake-file` options for [npins](https://github.com/andir/npins)-based dependency pinning.
157
-
- Exposes `write-npins` to generate/update the `npins/` directory from declared inputs.
158
-
- Supports `github`, `gitlab`, `channel`, `tarball`, and `git` URL schemes.
159
-
- Respects `follows` for transitive dependency deduplication.
160
-
- Prunes stale pins automatically.
161
-
- See [templates/npins](templates/npins) for usage.
162
-
163
-
#### [`flakeModules.unflake`](https://github.com/vic/flake-file/tree/main/modules/unflake.nix)
164
-
165
-
- Defines `flake-file` options.
166
-
- Exposes `write-unflake` to generate `unflake.nix` or `npins`. See [templates/unflake](templates/unflake) for usage.
167
-
168
-
### Flake Templates
169
-
170
-
#### [`default`](templates/default) template
171
-
172
-
A more basic, explicit setup.
173
-
174
-
```nix
175
-
# See templates/default
176
-
{ inputs, ... }: {
177
-
imports = [
178
-
inputs.flake-file.flakeModules.default
179
-
];
180
-
181
-
flake-file.inputs = {
182
-
flake-file.url = "github:vic/flake-file";
183
-
flake-parts.url = "github:hercules-ci/flake-parts";
184
-
nixpkgs.url = "github:nixos/nixpkgs/nixpkgs-unstable";
185
-
};
186
-
187
-
systems = inputs.nixpkgs.lib.systems.flakeExposed;
188
-
}
189
-
```
190
-
191
-
> [!IMPORTANT]
192
-
> Use `nix run .#write-flake` to generate.
193
-
194
-
> [!TIP]
195
-
> You can use the `write-flake` app as part of a devshell or git hook.
196
-
197
-
#### [`dendritic`](templates/dendritic) template
198
-
199
-
A template for dendritic setups; includes `flakeModules.dendritic`.
200
-
201
-
#### [`parts`](templates/parts) template
202
-
203
-
A template that uses `lib.flakeModules.flake-parts-builder`.
204
-
205
-
#### [`npins`](templates/npins) template
206
-
207
-
Uses [npins](https://github.com/andir/npins) to pin and fetch inputs defined as options for non-flakes stable Nix environments. Supports channels, GitHub, GitLab, tarballs, and git repos. Recommended for new non-flake projects.
208
-
209
-
#### [`unflake`](templates/unflake) template
210
-
211
-
Uses [goldstein/unflake](https://codeberg.org/goldstein/unflake) to pin and fetch inputs that were defined as options for non-flakes stable Nix environments.
212
-
213
-
---
214
-
215
-
## Available Options
216
-
217
-
Options use the same attributes as the flake schema. See below for details.
218
-
219
-
| Option | Description |
220
-
| ------------------------------------------------- | ----------------------------------------------------------- |
221
-
| `flake-file.description` | Sets the flake description |
222
-
| `flake-file.nixConfig` | Flake-level `nixConfig` (typed attrset) |
223
-
| `flake-file.outputs` | Literal Nix code for `outputs` function |
224
-
| `flake-file.formatter` | Function: `pkgs -> program` to format generated `flake.nix` |
225
-
| `flake-file.do-not-edit` | Header comment added atop generated file |
226
-
| `flake-file.inputs.<name>.url` | Source URL (e.g. `github:owner/repo`) |
227
-
| `flake-file.inputs.<name>.type` | Reference type (`github`, `path`, etc.) |
228
-
| `flake-file.inputs.<name>.owner` | Owner (for typed VCS refs) |
229
-
| `flake-file.inputs.<name>.repo` | Repo name |
230
-
| `flake-file.inputs.<name>.path` | Local path reference |
231
-
| `flake-file.inputs.<name>.id` | Flake registry id |
232
-
| `flake-file.inputs.<name>.dir` | Subdirectory within repo/path |
233
-
| `flake-file.inputs.<name>.narHash` | NAR hash pin |
234
-
| `flake-file.inputs.<name>.rev` | Commit hash pin |
235
-
| `flake-file.inputs.<name>.ref` | Branch or tag pin |
236
-
| `flake-file.inputs.<name>.host` | Custom host for git forges |
237
-
| `flake-file.inputs.<name>.submodules` | Whether to fetch git submodules |
238
-
| `flake-file.inputs.<name>.flake` | Boolean: is it a flake? (default true) |
239
-
| `flake-file.inputs.<name>.follows` | Follow another input's value |
240
-
| `flake-file.inputs.<name>.inputs.<dep>.follows` | Nested input follow tree |
241
-
| `flake-file.inputs.<name>.inputs.<dep>.inputs...` | Recursively follow deeper deps |
242
-
| `flake-file.write-hooks` | List of ordered hooks (by `index`) after writing |
243
-
| `flake-file.check-hooks` | List of ordered hooks (by `index`) during check |
244
-
| `flake-file.prune-lock.enable` | Enable automatic flake.lock pruning |
245
-
| `flake-file.prune-lock.program` | Function building pruning executable |
246
-
247
-
Example:
248
-
249
-
```nix
250
-
flake-file = {
251
-
description = "my awesome flake";
252
-
nixConfig = {}; # attrset (free-form, typed as attrs)
253
-
inputs.<name>.url = "github:foo/bar";
254
-
inputs.<name>.flake = false;
255
-
inputs.<name>.inputs.nixpkgs.follows = "nixpkgs";
256
-
};
257
-
```
258
-
259
-
> [!TIP]
260
-
> See also, [options.nix](https://github.com/vic/flake-file/blob/main/modules/options/default.nix).
261
-
262
-
---
263
-
264
-
## About the Flake `outputs` function
265
-
266
-
The `flake-file.outputs` option is a literal Nix expression. You cannot convert a Nix function value into a string for including in the generated flake file.
267
-
268
-
It defaults to:
269
-
270
-
```nix
271
-
inputs: import ./outputs.nix inputs
272
-
```
273
-
274
-
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](https://github.com/vic/flake-file/blob/main/modules/dendritic/dendritic.nix), but not for including a large Nix code string in it.
275
-
276
-
---
277
-
278
-
<a name="parts_templates"></a>
279
-
280
-
## Add flake-parts-builder templates
281
-
282
-
Tired of endlessly repeating tiny flake-parts modules or copy-pasting
283
-
snippets between your projects? No more!
284
-
285
-
[flake-parts-builder](https://github.com/tsandrini/flake-parts-builder)
286
-
lets you _incrementally_ add templated parts.
287
-
This is much better than normal flake templates, since flake-parts templates
288
-
can be added or removed at any time, not only at project initialization.
289
-
290
-
```nix
291
-
{ inputs, ... }: {
292
-
imports = [
293
-
(inputs.flake-file.lib.flakeModules.flake-parts-builder ./flake-parts)
294
-
];
295
-
}
296
-
```
297
-
298
-
> [!IMPORTANT]
299
-
> Use `github:vic/flake-parts-builder/write-meta` until [flake-parts-builder#60](https://github.com/tsandrini/flake-parts-builder/pull/60) gets merged. This branch will also write each parts meta.nix file, so it can be used by flake-file to manage your flake.nix.
300
-
301
-
> [!WARNING]
302
-
> Only use `flake-parts-builder add` subcommand, since `init` will _overwrite_ the flake.nix file that is already being managed by flake-file.
303
-
304
-
```shell
305
-
nix run github:vic/flake-parts-builder/write-meta -- add --write-meta --parts systems,treefmt $PWD
306
-
```
307
-
308
-
## Hooks for write-flake and checks
309
-
310
-
You can add custom commands to be run whenever your flake.nix has been
311
-
written or checked.
312
-
313
-
> [!TIP]
314
-
> See `flake-file.write-hooks` and `flake-file.check-hooks` options.
315
-
316
-
## Automatic flake.lock flattening
317
-
318
-
You can use the `prune-lock` [options](https://github.com/vic/flake-file/blob/main/modules/options/prune-lock.nix)
319
-
to specify a command that `flake-file` will use whenever your flake.nix file is generated
320
-
to flatten your flake.lock dependency tree.
321
-
322
-
For flattening mechanisms we provide:
323
-
324
-
- [`flakeModules.allfollow`](https://github.com/vic/flake-file/blob/main/modules/prune-lock/allfollow.nix) that enables this using [`spikespaz/allfollow`](https://github.com/spikespaz/allfollow)
325
-
- [`flakeModules.nix-auto-follow`](https://github.com/vic/flake-file/blob/main/modules/prune-lock/nix-auto-follow.nix) that enables this using [`fzakaria/nix-auto-follow`](https://github.com/fzakaria/nix-auto-follow)
326
-
327
-
```nix
328
-
{ inputs, ... }:
329
-
{
330
-
imports = [
331
-
inputs.flake-file.flakeModules.nix-auto-follow
332
-
# or optionally
333
-
# inputs.flake-file.flakeModules.allfollow
334
-
];
335
-
}
336
-
```
337
-
338
-
---
339
-
340
-
## Migration Guide
341
-
342
-
This section outlines the recommended steps for adopting `flake-file` in your own repository.
343
-
344
-
1. **Prerequisite:** Ensure you have already adopted [flake-parts](https://flake.parts).
345
-
346
-
1. **Add Inputs:** In your current `flake.nix`, add the following input:
347
-
348
-
```nix
349
-
flake-file.url = "github:vic/flake-file";
350
-
```
351
-
352
-
1. **Move Outputs:** Copy the contents of your `outputs` function into a file `./outputs.nix`:
353
-
354
-
```nix
355
-
# outputs.nix -- this is the contents of your `outputs` function from the original flake.nix file.
356
-
inputs: inputs.flake-parts.lib.mkFlake { inherit inputs; } {
357
-
imports = [
358
-
./modules/inputs.nix # Add this for step 4.
359
-
# Feel free to split ./modules/inputs.nix into other modules as you see fit.
360
-
# If you end having lots of modules, consider using import-tree for auto importing them.
361
-
];
362
-
}
363
-
```
364
-
365
-
1. **Move Inputs:** Copy your current flake.nix file as a flake-parts module (e.g., `modules/inputs.nix`):
366
-
367
-
> [!IMPORTANT]
368
-
> Make sure you `git add` so that new files are visible to Nix.
369
-
370
-
```nix
371
-
# modules/inputs.nix
372
-
{ inputs, ... }:
373
-
{
374
-
imports = [
375
-
inputs.flake-file.flakeModules.default # flake-file options.
376
-
];
377
-
flake-file = {
378
-
inputs = {
379
-
flake-file.url = "github:vic/flake-file";
380
-
# ... all your other original flake inputs here.
381
-
};
382
-
nixConfig = { }; # if you had any.
383
-
description = "Your flake description";
384
-
};
385
-
}
386
-
```
387
-
388
-
5. **Backup:** Back up your flake.nix into flake.nix.bak before regenerating it.
389
-
1. **Generate:** Execute `nix run .#write-flake` to generate flake.nix.
390
-
1. **Verify:** Check flake.nix and if everything is okay, remove the backup file.
391
-
392
-
You are done! Now you can split dependencies from `modules/inputs.nix` into other flake-part modules as you see fit:
393
-
394
-
```nix
395
-
# ./modules/<name>.nix -- Replace `<name>` with some dependency.
396
-
{ inputs, lib, ... }: {
397
-
flake-file.inputs.<name>.url = ...;
398
-
399
-
# Example usage: include the flakeModule once it has been added to flake.nix.
400
-
imports = lib.optionals (inputs ? <name>) [ inputs.<name>.flakeModule ];
401
-
}
402
-
```
403
-
404
-
---
405
-
406
-
## Bootstrapping
407
-
408
-
You can generate `flake.nix`, `inputs.nix`, `unflake.nix` or `npins` by using the following command:
409
-
410
-
```shell
411
-
# create a bootstrap module. add any dependencies you want
412
-
echo '{ flake-file.inputs.flake-file.url = "github:vic/flake-file"; }' > bootstrap.nix # filename is not important
413
-
414
-
# replace write-flake with: write-inputs / write-unflake / write-npins
415
-
nix-shell https://github.com/vic/flake-file/archive/refs/heads/main.zip -A flake-file.sh --run write-flake --arg modules ./bootstrap.nix
416
-
```
417
-
418
-
`bootstrap.nix` can also be a `./modules` directory that will be auto-imported using import-tree.
419
-
420
-
## Development
421
-
422
-
Use `nix develop ./dev` or with direnv: `use flake ./dev`.
423
-
424
-
```shell
425
-
[[general commands]]
426
-
427
-
check - run flake check
428
-
fmt - format all files in repo
429
-
menu - prints this menu
430
-
regen - regenerate all flake.nix files in this repo
431
-
```
432
-
433
-
---
434
-
435
-
## Contributing & Support
436
-
437
-
- Found a bug or have a feature request? [Open an issue](https://github.com/vic/flake-file/issues).
438
-
- Contributions are welcome!
439
-
440
-
---
441
-
442
-
Made with \<3 by [@vic](https://x.com/oeiuwq)
53
+
## Learn more: [Documentation](https://flake-file.oeiuwq.com)