### Initial non-flake default.nix

Source: https://github.com/denful/flake-file/blob/main/docs/src/content/docs/tutorials/migrate-no-flakes.mdx

Example of a traditional Nix default.nix file before migration.

```nix
# default.nix
let
  sources = import ./npins;
in
{
  nixosConfigurations.my-laptop = ...; # use sources
}
```

--------------------------------

### Start Local Development Server

Source: https://github.com/denful/flake-file/blob/main/docs/README.md

This command starts a local development server, typically accessible at `localhost:4321`, for previewing your site during development.

```bash
pnpm dev
```

--------------------------------

### Using the Dendritic flakeModule

Source: https://context7.com/denful/flake-file/llms.txt

This example demonstrates using the `flakeModules.dendritic` module for a batteries-included setup. It automatically includes flake-parts and import-tree defaults.

```nix
# modules/default.nix
{
  inputs, lib,
}: {
  imports = [ inputs.flake-file.flakeModules.dendritic ];

  flake-file = {
    description = "My Dendritic Project";
    inputs.nixpkgs.url     = lib.mkDefault "github:NixOS/nixpkgs/nixpkgs-unstable";
    inputs.nixpkgs-lib.follows = "nixpkgs";
    # flake-parts and import-tree are added automatically by the dendritic module
  };
}
# Generates outputs: inputs: inputs.flake-parts.lib.mkFlake { inherit inputs; } (inputs.import-tree ./modules)

```

--------------------------------

### Using unflake and nixlock flakeModules

Source: https://context7.com/denful/flake-file/llms.txt

This example shows how to use `flakeModules.unflake` and `flakeModules.nixlock` to generate `unflake.nix` or `nixlock.lock.nix` from `flake-file.inputs` declarations.

```nix
# modules/default.nix — unflake
{
  inputs, ...
}: {
  imports = [ inputs.flake-file.flakeModules.unflake ];
  flake-file.inputs.nixpkgs.url = "github:NixOS/nixpkgs/nixpkgs-unstable";
}

```

--------------------------------

### Install Project Dependencies

Source: https://github.com/denful/flake-file/blob/main/docs/README.md

Run this command in the root of your project to install all necessary dependencies defined in `package.json`.

```bash
pnpm install
```

--------------------------------

### Create Astro Project with Starlight Template

Source: https://github.com/denful/flake-file/blob/main/docs/README.md

Use this command to initialize a new Astro project with the Starlight template. Ensure you have pnpm installed.

```bash
pnpm create astro@latest -- --template starlight
```

--------------------------------

### Initialize Project from Template

Source: https://context7.com/denful/flake-file/llms.txt

Commands to initialize a new project using flake-file's built-in templates. After initialization, generate flake.nix and verify the setup.

```shell
# Minimal explicit setup (default)
nix flake init -t github:vic/flake-file#default

# Dendritic — batteries-included with flake-parts and import-tree
nix flake init -t github:vic/flake-file#dendritic

# flake-parts-builder integration
nix flake init -t github:vic/flake-file#parts

# Non-flake / stable Nix with npins
nix flake init -t github:vic/flake-file#npins

# Non-flake / stable Nix with unflake
nix flake init -t github:vic/flake-file#unflake

# Non-flake / stable Nix with nixlock
nix flake init -t github:vic/flake-file#nixlock

# After initialising any template, generate flake.nix and verify
nix run ".#write-flake"
nix flake check
```

--------------------------------

### flake-file Configuration After Migration

Source: https://context7.com/denful/flake-file/llms.txt

This is an example of a `flake-file.nix` after migrating from a traditional `flake.nix`. It shows a full Nix configuration without restrictions and includes an optional output schema validation.

```nix
# flake-file.nix (after migration) — full real Nix, no restrictions
{
  lib,
  ...
}: {
  flake-file.inputs.nixpkgs.url = lib.mkDefault "github:NixOS/nixpkgs/nixpkgs-unstable";

  outputs = inputs: {
    hello = "mundo";
  };

  # Optionally validate outputs with a typed schema
  flake-file.outputs-schema = {
    lib,
    ...
  }: {
    options.hello = lib.mkOption {
      type = lib.types.enum [ "mundo" "monde" ];
    };
  };
}

```

--------------------------------

### Configure flake-file Inputs

Source: https://github.com/denful/flake-file/blob/main/docs/src/content/docs/reference/options.mdx

Example demonstrating how to configure flake inputs, including direct URL references, following other inputs, and disabling flake detection for specific tools.

```nix
flake-file = {
  description = "my awesome flake";
  nixConfig = {};
  inputs.nixpkgs.url = "github:NixOS/nixpkgs/nixpkgs-unstable";
  inputs.nixpkgs-lib.follows = "nixpkgs";
  inputs.my-tool.flake = false;
  inputs.my-tool.url = "github:owner/my-tool";
  inputs.dep.inputs.nixpkgs.follows = "nixpkgs";
};

```

--------------------------------

### Create new default.nix for modular setup

Source: https://github.com/denful/flake-file/blob/main/docs/src/content/docs/tutorials/migrate-no-flakes.mdx

A new default.nix file that leverages Nix Modules and resolves inputs using the npins generated from the flake-file.nix.

```nix
# default.nix
let
  sources = import ./npins;
  nixpkgs = import sources.nixpkgs { };
  outputs = (nixpkgs.lib.evalModules {
    modules = ./modules;
    specialArgs = {
      inputs = sources; # (A) NOTE: Not flake-like inputs.
    };
  }).config;
in
outputs
```

--------------------------------

### Generate unflake.nix with Options

Source: https://github.com/denful/flake-file/blob/main/templates/unflake/README.md

Pass any unflake option to the `write-unflake` command. This example shows how to specify the verbose flag and the nix backend.

```shell
nix-shell . -A flake-file.sh --run 'write-unflake --verbose --backend nix'
```

--------------------------------

### Bootstrap flake-file

Source: https://github.com/denful/flake-file/blob/main/README.md

Use this command to bootstrap flake-file. It renames your existing flake.nix and installs flake-file.

```shell
mv flake.nix flake-file.nix
nix-shell https://github.com/vic/flake-file/archive/main.zip -A flake-file.sh --run bootstrap
```

--------------------------------

### Move project files to modules directory

Source: https://github.com/denful/flake-file/blob/main/docs/src/content/docs/tutorials/migrate-no-flakes.mdx

Organize your existing default.nix and flake-file.nix into a new 'modules' directory for a modular setup.

```shell
mkdir modules
mv flake-file.nix modules/inputs.nix
mv default.nix modules/default.nix
```

--------------------------------

### Create temporary directory for bootstrapping

Source: https://github.com/denful/flake-file/blob/main/docs/src/content/docs/tutorials/bootstrap.mdx

Create a temporary directory and navigate into it to safely experiment with the bootstrap command without affecting your existing flake setup.

```shell
mkdir bootstrap
cd bootstrap
```

--------------------------------

### Get Help with Astro CLI

Source: https://github.com/denful/flake-file/blob/main/docs/README.md

Displays help information for the Astro CLI, useful for understanding available commands and options.

```bash
pnpm astro -- --help
```

--------------------------------

### Import flake-parts-builder Module

Source: https://github.com/denful/flake-file/blob/main/docs/src/content/docs/guides/flake-parts-builder.mdx

Import the flake-parts-builder module to enable dynamic loading of flake-parts. This setup bootstraps the builder, auto-loads Nix modules, and reads flake-file configurations from each part's _meta/ directory.

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

--------------------------------

### Overriding flake-file.outputs for a One-liner

Source: https://github.com/denful/flake-file/blob/main/docs/src/content/docs/guides/outputs.mdx

An example of overriding `flake-file.outputs` for a simple, legitimate one-liner, such as setting up `dendritic`.

```nix
inputs: inputs.flake-parts.lib.mkFlake { inherit inputs; } (inputs.import-tree ./modules)
```

--------------------------------

### Default flake.nix Configuration

Source: https://github.com/denful/flake-file/blob/main/docs/src/content/docs/guides/templates.mdx

A minimal and explicit Nix flake configuration using flake-parts. This serves as a basic setup without additional framework dependencies.

```nix
# flake-parts module — 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 = inputs.nixpkgs.lib.systems.flakeExposed;
}
```

--------------------------------

### Import flakeModules.dendritic

Source: https://github.com/denful/flake-file/blob/main/docs/src/content/docs/guides/flake-modules.mdx

Use the dendritic module for a batteries-included setup for Dendritic projects. It includes the default module, import-tree, flake-parts, and sets up default outputs.

```nix
{ inputs, lib, ... }:
{
  imports = [ inputs.flake-file.flakeModules.dendritic ];

  flake-file = {
    description = "My Awesome Flake";
    inputs.nixpkgs.url = lib.mkDefault "github:NixOS/nixpkgs/nixpkgs-unstable";
    inputs.nixpkgs-lib.follows = "nixpkgs";
  };
}
```

--------------------------------

### Declare flake-file Inputs with Nix Modules

Source: https://github.com/denful/flake-file/blob/main/docs/src/content/docs/explanation/how-it-works.mdx

Example of how to declare flake-file inputs within a Nix module, using lib.mkDefault for initial values and follows for referencing existing inputs.

```nix
{ inputs, lib, ... }:
{
  flake-file.inputs.nixpkgs.url = lib.mkDefault "github:NixOS/nixpkgs/nixpkgs-unstable";
  flake-file.inputs.nixpkgs-lib.follows = "nixpkgs";
}
```

--------------------------------

### Add write-hook to update flake

Source: https://github.com/denful/flake-file/blob/main/docs/src/content/docs/guides/hooks.mdx

Use write-hooks to trigger follow-up actions whenever `flake.nix` is regenerated. This example runs `nix flake update` after `flake.nix` is written.

```nix
{ pkgs, ... }:
{
  flake-file.write-hooks = [
    {
      index = 10;
      exec = "${pkgs.nix}/bin/nix flake update";
    }
  ];
}
```

--------------------------------

### Declare Flake Inputs with flake-file

Source: https://context7.com/denful/flake-file/llms.txt

Example of declaring flake inputs as typed module options within a Nix module. Demonstrates standard GitHub inputs, following other inputs, non-flake sources, typed references, pinning to specific commits, flattening dependencies, and conditional inputs.

```nix
# modules/inputs.nix
{ lib, ... }:
{
  flake-file.inputs = {
    # Standard GitHub input
    nixpkgs.url = lib.mkDefault "github:NixOS/nixpkgs/nixpkgs-unstable";

    # Follow another input so transitive deps are shared
    nixpkgs-lib.follows = "nixpkgs";

    # Non-flake source archive
    my-tool.flake = false;
    my-tool.url   = "github:owner/my-tool";

    # Typed reference (no url string needed)
    my-lib = {
      type  = "github";
      owner = "some-owner";
      repo  = "some-repo";
      ref   = "main";
    };

    # Pin to a specific commit
    pinned-dep.url = "github:owner/repo";
    pinned-dep.rev = "abc1234def5678";

    # Flatten a transitive dependency
    dep.inputs.nixpkgs.follows = "nixpkgs";

    # Conditional input (only when some condition applies)
    optional-tool.url = lib.mkIf true "github:owner/optional-tool";
  };
}
```

--------------------------------

### Distribute input declarations to modules

Source: https://github.com/denful/flake-file/blob/main/docs/src/content/docs/tutorials/migrate.mdx

To make modules self-contained, move input declarations from modules/inputs.nix to the specific modules that use them. This example shows how to declare an input for 'my-tool' within its own module.

```nix
# modules/my-tool.nix
{ inputs, lib, ... }:
{
  flake-file.inputs.my-tool.url = lib.mkDefault "github:owner/my-tool";
  imports = lib.optionals (inputs ? my-tool) [ inputs.my-tool.flakeModule ];
}
```

--------------------------------

### Initialize New Project with flake-file Template

Source: https://github.com/denful/flake-file/blob/main/docs/src/content/docs/tutorials/quick-start.mdx

Use this command to initialize a new project using a `flake-file` template. This is suitable for brand new projects, with or without existing flakes.

```shell
nix flake init -t github:vic/flake-file#default
```

--------------------------------

### Generate unflake.nix

Source: https://github.com/denful/flake-file/blob/main/templates/unflake/README.md

Use this command to generate the `unflake.nix` file. It first creates a temporary `inputs.nix` from your configuration and then runs unflake.

```shell
nix-shell . -A flake-file.sh --run write-unflake
```

--------------------------------

### Add check-hook for validation

Source: https://github.com/denful/flake-file/blob/main/docs/src/content/docs/guides/hooks.mdx

Use check-hooks to add extra validation during `nix flake check`. This example runs a linter to check the current directory.

```nix
{ pkgs, ... }:
{
  flake-file.check-hooks = [
    {
      index = 10;
      exec = "${pkgs.my-linter}/bin/my-linter --check .";
    }
  ];
}
```

--------------------------------

### Bootstrap flake.nix using a modules directory

Source: https://github.com/denful/flake-file/blob/main/docs/src/content/docs/tutorials/bootstrap.mdx

Bootstrap a `flake.nix` by providing a directory of `.nix` files as modules. These files will be auto-imported, which is useful when you have existing module files and need an initial `flake.nix`.

```shell
nix-shell https://github.com/vic/flake-file/archive/refs/heads/main.zip \
  -A flake-file.sh --run write-flake --arg modules ./modules
```

--------------------------------

### flake-file Workflow Diagram

Source: https://github.com/denful/flake-file/blob/main/docs/src/content/docs/explanation/how-it-works.mdx

Illustrates the process of declaring flake-file options in modules, running the write-flake command, and updating the flake.nix file.

```text
edit modules/*.nix     # declare flake-file options
  ↓
nix run .#write-flake  # extracts inputs and serializes
  ↓ 
flake.nix              # updated and locked
```

--------------------------------

### Dendritic Project Initialization and Checks

Source: https://github.com/denful/flake-file/blob/main/docs/src/content/docs/guides/templates.mdx

Commands to initialize a Dendritic project using the `dendritic` template, generate the `flake.nix`, and perform a flake check.

```shell
nix flake init -t github:vic/flake-file#dendritic
nix run ".#write-flake"
nix flake check
```

--------------------------------

### Preview Production Build

Source: https://github.com/denful/flake-file/blob/main/docs/README.md

Allows you to preview the production build locally before deploying it.

```bash
pnpm preview
```

--------------------------------

### Build Production Site

Source: https://github.com/denful/flake-file/blob/main/docs/README.md

Generates a production-ready build of your website in the `./dist/` directory.

```bash
pnpm build
```

--------------------------------

### Verify and clean up after migration

Source: https://github.com/denful/flake-file/blob/main/docs/src/content/docs/tutorials/migrate.mdx

Inspect the generated flake.nix to ensure correctness. Run `nix flake check` to verify the flake's integrity. Remove the backup file if satisfied.

```shell
cat flake.nix            # inspect the generated file
nix flake check          # verify everything is in sync
rm flake.nix.bak         # clean up if happy
```

--------------------------------

### Initialize unflake Template

Source: https://github.com/denful/flake-file/blob/main/docs/src/content/docs/guides/templates.mdx

Use this command to initialize a project for a non-flake (stable Nix) environment using the `unflake` template, which leverages goldstein/unflake for input pinning.

```shell
nix flake init -t github:vic/flake-file#unflake
```

--------------------------------

### Import flakeModules.default

Source: https://github.com/denful/flake-file/blob/main/docs/src/content/docs/guides/flake-modules.mdx

Import the base module to access all flake-file options, the write-flake app, and flake checks.

```nix
{ inputs, ... }:
{
  imports = [ inputs.flake-file.flakeModules.default ];
}
```

--------------------------------

### Original flake.nix with flake-parts

Source: https://github.com/denful/flake-file/blob/main/docs/src/content/docs/tutorials/migrate-flake-parts.mdx

This is the initial structure of a flake.nix file using flake-parts, defining inputs and the flake-parts entry-point module.

```nix
# flake.nix
{
  inputs = { # (A) So much inputs
    nixpkgs.url = "github:nixos/nixpkgs/nixos-unstable";
    flake-parts.url = "github:hercules-ci/flake-parts";
    foo.url = "github:coolguy/foo";
    bar.url = "github:coolguy/bar";
  };
  outputs = inputs:
    inputs.flake-parts.lib.mkFlake { inherit inputs; } 
      # (B) flake-parts entry-point module.
      {
        systems = [ "aarch64-darwin" ];
        ...
      };
}
```

--------------------------------

### Define flake-file.nix inputs

Source: https://github.com/denful/flake-file/blob/main/docs/src/content/docs/tutorials/migrate-no-flakes.mdx

Create a flake-file.nix to define your project's inputs, similar to a flake's inputs.

```nix
# flake-file.nix
{
  flake-file.inputs = {
    nixpkgs.url = "github:nixos/nixpkgs/nixpkgs-unstable";
  };
}
```

--------------------------------

### Run flake-file.sh via nix-shell

Source: https://github.com/denful/flake-file/blob/main/docs/src/content/docs/reference/bootstrap.mdx

This command fetches the `flake-file.sh` app from a specific GitHub release and executes it within a `nix-shell`. Use this as the entry point for generating flake files.

```shell
nix-shell https://github.com/vic/flake-file/archive/refs/heads/main.zip \
  -A flake-file.sh --run <app> [--arg <name> <value>]...
```

--------------------------------

### Adding flake-parts-builder Parts and Regenerating

Source: https://context7.com/denful/flake-file/llms.txt

Commands to add parts using `flake-parts-builder` and then regenerate the `flake.nix` to include new inputs. It also includes a check for flake integrity.

```shell
# Add parts (use write-meta branch until PR#60 is merged)
nix run github:vic/flake-parts-builder/write-meta -- \
  add --write-meta --parts systems,treefmt $PWD

# Regenerate flake.nix to pick up new inputs declared by added parts
nix run ".#write-flake"
nix flake check

```

--------------------------------

### Bootstrap flake-file

Source: https://github.com/denful/flake-file/blob/main/docs/src/content/docs/index.mdx

Use this command to bootstrap flake-file into your project. It involves renaming your existing flake.nix and then running the bootstrap script.

```shell
mv flake.nix flake-file.nix
nix-shell https://github.com/vic/flake-file/archive/main.tar.gz -A flake-file.sh --run bootstrap
```

--------------------------------

### Initialize flake-file Template

Source: https://github.com/denful/flake-file/blob/main/docs/src/content/docs/guides/templates.mdx

Use this command to initialize a new project with a specific flake-file template. Replace `<template>` with the desired template name (e.g., `default`, `dendritic`, `npins`).

```shell
nix flake init -t github:vic/flake-file#<template>
```

--------------------------------

### Write a minimal flake.nix using bootstrap

Source: https://github.com/denful/flake-file/blob/main/docs/src/content/docs/tutorials/bootstrap.mdx

Use the `flake-file` Nix shell to write a minimal `flake.nix` file. This command takes a `flake-file.nix` as input and generates the `flake.nix`.

```shell
# Write a minimal flake-file.nix file (or copy a flake.nix of yours)
echo '{ inputs.flake-file.url = "github:vic/flake-file"; }' > flake-file.nix

# Generate flake.nix or unflake.nix or npins or nixlock from flake-file.nix
nix-shell https://github.com/vic/flake-file/archive/refs/heads/main.zip \
  -A flake-file.sh --run write-flake --arg modules ./flake-file.nix
```

--------------------------------

### Generate unflake.nix with npins Backend

Source: https://github.com/denful/flake-file/blob/main/templates/unflake/README.md

Use this command to generate `unflake.nix` with the npins backend enabled. This allows unflake to integrate with npins for managing inputs.

```shell
nix-shell . -A flake-file.sh --run 'write-unflake --backend npins'
```

--------------------------------

### Manually Run Unflake

Source: https://github.com/denful/flake-file/blob/main/templates/unflake/README.md

After generating the temporary `inputs.nix`, you can manually run unflake using this command. This is useful for debugging or fine-grained control.

```shell
# then, you can run unflake yourself:
nix-shell https://ln-s.sh/unflake -A unflake-shell --run unflake
```

--------------------------------

### Integrating with flake-parts-builder

Source: https://context7.com/denful/flake-file/llms.txt

This snippet demonstrates how to integrate `flake-file` with `flake-parts-builder` to manage templated flake-parts modules. It shows how to pass the directory containing the parts.

```nix
# modules/default.nix
{
  inputs, ...
}: {
  imports = [
    # Pass the directory where flake-parts-builder parts live
    (inputs.flake-file.lib.flakeModules.flake-parts-builder ./flake-parts)
  ];
  # _meta/ files inside ./flake-parts/<part>/ are auto-loaded as flake-file config
}

```

--------------------------------

### Split flake.nix into modules

Source: https://github.com/denful/flake-file/blob/main/docs/src/content/docs/tutorials/migrate-flake-parts.mdx

Move the flake-parts entry-point module and inputs into separate files within a 'modules' directory.

```nix
# modules/default.nix
{
  imports = [ ./inputs.nix ];
  systems = [ "aarch64-darwin" ];

  ...
  # same code as before
}
```

```nix
# modules/inputs.nix
# This is now real Nix code, use let bindings, { lib, ... } etc.
# best practice is to split this inputs.nix into other modules
{
  flake-file.inputs = {
    nixpkgs.url = "github:nixos/nixpkgs/unstable";
    flake-parts.url = "github:hercules-ci/flake-parts";
    # all your other inputs
  };
}
```

--------------------------------

### Migrating flake-parts Flake to flake-file

Source: https://context7.com/denful/flake-file/llms.txt

This command demonstrates how to adopt `flake-file` in an existing flake-parts project. It bootstraps the process using existing modules and the specified outputs style.

```shell
# Step 1 — bootstrap with existing modules and outputs style
nix-shell https://github.com/vic/flake-file/archive/main.tar.gz \
  -A flake-file.sh --run write-flake \
  --arg modules ./modules --argstr outputs flake-parts

```

--------------------------------

### Set flake description and nixConfig

Source: https://context7.com/denful/flake-file/llms.txt

Configure the top-level `description` string and `nixConfig` attribute set for the generated `flake.nix`.

```nix
# modules/meta.nix
{ ... }:
{
  flake-file.description = "My awesome project";

  flake-file.nixConfig = {
    extra-substituters      = [ "https://my-cache.cachix.org" ];
    extra-trusted-public-keys = [ "my-cache.cachix.org-1:abc123==" ];
  };
}
```

--------------------------------

### Backup and regenerate flake.nix

Source: https://github.com/denful/flake-file/blob/main/docs/src/content/docs/tutorials/migrate.mdx

Before regenerating, back up your current flake.nix. Then, use the nix run command to generate the new flake.nix file based on your configurations.

```shell
cp flake.nix flake.nix.bak
nix run .#write-flake
```

--------------------------------

### Import allfollow Module

Source: https://github.com/denful/flake-file/blob/main/docs/src/content/docs/guides/lock-flattening.mdx

Import the allfollow flake module to automatically add 'follows' entries for all transitive inputs. This is a built-in module provided by flake-file.

```nix
{ inputs, ... }:
{
  imports = [ inputs.flake-file.flakeModules.allfollow ];
}
```

--------------------------------

### Bootstrap flake.nix generation

Source: https://github.com/denful/flake-file/blob/main/docs/src/content/docs/tutorials/migrate-flake-parts.mdx

Use the flake-file bootstrap command to generate the flake.nix file from the modules directory.

```shell
nix-shell https://github.com/vic/flake-file/archive/main.tar.gz \
  -A flake-file.sh --run write-flake \
  --arg modules ./modules --argstr outputs flake-parts
```

--------------------------------

### Initialize npins Template

Source: https://github.com/denful/flake-file/blob/main/docs/src/content/docs/guides/templates.mdx

Use this command to initialize a project for a non-flake (stable Nix) environment using the `npins` template, which manages input pinning.

```shell
nix flake init -t github:vic/flake-file#npins
```

--------------------------------

### Add New Parts with flake-parts-builder

Source: https://github.com/denful/flake-file/blob/main/docs/src/content/docs/guides/flake-parts-builder.mdx

Use the `nix run` command with the `write-meta` branch of flake-parts-builder to add new parts. This command generates the necessary _meta/ files for flake-file to manage the part's inputs. Only use the `add` subcommand; avoid `init` as it overwrites flake.nix.

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

--------------------------------

### Migrating Traditional Flake to flake-file

Source: https://context7.com/denful/flake-file/llms.txt

This section outlines the steps to migrate a traditional `flake.nix` project to use `flake-file`. It involves renaming the `flake.nix` file and running the `bootstrap` command.

```shell
# Step 1 — rename flake.nix; bootstrap does the rest
mv flake.nix flake-file.nix
nix-shell https://github.com/vic/flake-file/archive/main.tar.gz \
  -A flake-file.sh --run bootstrap
# A new static flake.nix is generated; flake-file.nix becomes the real Nix module.

# Step 2 — re-run any time inputs change
nix-shell https://github.com/vic/flake-file/archive/main.zip \
  -A flake-file.sh --run bootstrap

```

--------------------------------

### Correctly Setting flake-file.outputs as a String

Source: https://github.com/denful/flake-file/blob/main/docs/src/content/docs/guides/outputs.mdx

Demonstrates the correct way to set `flake-file.outputs` using a Nix string literal, suitable for embedding expressions.

```nix
''inputs: inputs.flake-parts.lib.mkFlake { inherit inputs; } { }''
```

--------------------------------

### Generate Temporary Inputs.nix for Debugging

Source: https://github.com/denful/flake-file/blob/main/templates/unflake/README.md

This command generates the temporary `inputs.nix` file that is passed to unflake. It is recommended for debugging purposes only.

```shell
# (only recommended for debugging)
nix-shell . -A flake-file.sh --run write-inputs
```

--------------------------------

### Bootstrap flake.nix Generation

Source: https://context7.com/denful/flake-file/llms.txt

Commands to generate a flake.nix from scratch using flake-file. Supports various configurations like targeting different backends, using module directories, including predefined bootstrap inputs, or specifying output directories and overriding the outputs expression.

```shell
# Create a minimal declaration file
echo '{ inputs.flake-file.url = "github:vic/flake-file"; }' > flake-file.nix

# Generate flake.nix from flake-file.nix
nix-shell https://github.com/vic/flake-file/archive/refs/heads/main.zip \
  -A flake-file.sh --run write-flake --arg modules ./flake-file.nix

# Or target a different backend
nix-shell https://github.com/vic/flake-file/archive/refs/heads/main.zip \
  -A flake-file.sh --run write-npins --arg modules ./flake-file.nix

# Use a modules directory (all .nix files auto-imported)
nix-shell https://github.com/vic/flake-file/archive/refs/heads/main.zip \
  -A flake-file.sh --run write-flake --arg modules ./modules

# Include predefined bootstrap inputs (flake-file, nixpkgs, flake-parts, import-tree)
nix-shell https://github.com/vic/flake-file/archive/refs/heads/main.zip \
  -A flake-file.sh --run write-flake --arg modules ./flake-file.nix \
  --arg bootstrap true

# Include only specific bootstrap inputs
nix-shell https://github.com/vic/flake-file/archive/refs/heads/main.zip \
  -A flake-file.sh --run write-flake --arg modules ./flake-file.nix \
  --arg bootstrap '["flake-file" "nixpkgs"]'

# Write output to a specific directory (use --argstr, not --arg)
nix-shell https://github.com/vic/flake-file/archive/refs/heads/main.zip \
  -A flake-file.sh --run write-flake --arg modules ./flake-file.nix \
  --argstr outdir ./my-project

# Override the outputs expression
nix-shell https://github.com/vic/flake-file/archive/refs/heads/main.zip \
  -A flake-file.sh --run write-flake --arg modules ./modules \
  --argstr outputs flake-parts
```

--------------------------------

### Delegate flake outputs

Source: https://context7.com/denful/flake-file/llms.txt

Configure how flake outputs are delegated. Use 'default' for implicit delegation to ./outputs.nix, 'flake-parts' for flake-parts integration, 'dendritic' for Dendritic/import-tree, or a custom literal string.

```nix
{ ... }:
{
  # Default: delegates to ./outputs.nix (implicit, no need to set)
  # flake-file.outputs = "default";   # → inputs: import ./outputs.nix inputs

  # Named shorthand for flake-parts entry point
  flake-file.outputs = "flake-parts";
  # generates: inputs: inputs.flake-parts.lib.mkFlake { inherit inputs; } ./modules

  # Named shorthand for Dendritic / import-tree combo
  # flake-file.outputs = "dendritic";
  # generates: inputs: inputs.flake-parts.lib.mkFlake { inherit inputs; } (inputs.import-tree ./modules)

  # Fully custom literal string (must be a string, not a Nix function value)
  # flake-file.outputs = ''inputs: inputs.flake-parts.lib.mkFlake { inherit inputs; } { }'';
}
```

--------------------------------

### Importing Default flake-file Module

Source: https://context7.com/denful/flake-file/llms.txt

This snippet shows how to import the default flake-file module into a flake-parts project. It sets up basic project configuration and input definitions.

```nix
{ inputs, lib, ... }:
{
  imports = [ inputs.flake-file.flakeModules.default ];

  flake-file = {
    description = "My project";
    inputs.nixpkgs.url = lib.mkDefault "github:NixOS/nixpkgs/nixpkgs-unstable";
    inputs.nixpkgs-lib.follows  = "nixpkgs";
    inputs.flake-file.url       = "github:vic/flake-file";
    inputs.flake-parts.url      = "github:hercules-ci/flake-parts";
  };

  systems = inputs.nixpkgs.lib.systems.flakeExposed;
}

```

--------------------------------

### Astro + Starlight Project Structure

Source: https://github.com/denful/flake-file/blob/main/docs/README.md

This is the typical directory structure for an Astro project using Starlight. Markdown/MDX files for documentation should be placed in `src/content/docs/`.

```bash
.\n├── public/\n├── src/\n│   ├── assets/\n│   ├── content/\n│   │   └── docs/\n│   └── content.config.ts\n├── astro.config.mjs\n├── package.json\n└── tsconfig.json
```

--------------------------------

### Create modules/inputs.nix for flake-file

Source: https://github.com/denful/flake-file/blob/main/docs/src/content/docs/tutorials/migrate.mdx

Create a new flake-parts module to declare flake-file inputs and configurations. This file will contain the flake-file specific settings and original input declarations.

```nix
# modules/inputs.nix
{ inputs, ... }:
{
  imports = [
    inputs.flake-file.flakeModules.default
  ];

  flake-file = {
    description = "Your flake description";
    inputs = {
      flake-file.url = "github:vic/flake-file";
      # ... all your original inputs here
    };
    nixConfig = { }; # if you had any
  };
}
```

--------------------------------

### Import nix-auto-follow Module

Source: https://github.com/denful/flake-file/blob/main/docs/src/content/docs/guides/lock-flattening.mdx

Import the nix-auto-follow flake module to detect duplicate inputs and inject 'follows' for them. This module is part of flake-file's built-in support.

```nix
{ inputs, ... }:
{
  imports = [ inputs.flake-file.flakeModules.nix-auto-follow ];
}
```

--------------------------------

### Define write and check hooks

Source: https://context7.com/denful/flake-file/llms.txt

Specify shell commands to run after `write-flake` generates `flake.nix` (write-hooks) or during `nix flake check` (check-hooks). Hooks are merged and run by `index` order.

```nix
# modules/hooks.nix
{ pkgs, ... }:
{
  # Automatically update flake.lock after every regeneration
  flake-file.write-hooks = [
    {
      index = 10;
      exec  = "${pkgs.nix}/bin/nix flake update";
    }
    {
      index = 20;
      exec  = "${pkgs.git}/bin/git add flake.nix flake.lock";
    }
  ];

  # Validate a derived file is up to date in CI
  flake-file.check-hooks = [
    {
      index = 10;
      exec  = "${pkgs.my-linter}/bin/my-linter --check .";
    }
  ];
}
```

--------------------------------

### Generate nixlock.lock.nix

Source: https://github.com/denful/flake-file/blob/main/templates/nixlock/README.md

Use this command to generate the nixlock.lock.nix file for your project. This command is a convenience wrapper provided by the template.

```shell
nix-shell . -A flake-file.sh --run write-nixlock
```

--------------------------------

### Configuring Non-Flake Backend with npins

Source: https://context7.com/denful/flake-file/llms.txt

This snippet shows how to use the `flakeModules.npins` module to manage an `npins/` pin directory from standard `flake-file.inputs`. It supports various URL schemes for inputs.

```nix
# modules/default.nix
{
  inputs, ...
}: {
  imports = [ inputs.flake-file.flakeModules.npins ];

  flake-file.inputs = {
    flake-file.url  = "github:vic/flake-file";
    import-tree.url = "github:vic/import-tree";
    nixpkgs.url     = "https://channels.nixos.org/nixpkgs-unstable/nixexprs.tar.xz";
  };
}

```

--------------------------------

### Declare Inputs for Non-Flake Project

Source: https://context7.com/denful/flake-file/llms.txt

Declare inputs using flake-like URLs for a stable-Nix project that uses npins.

```nix
{ ... }:
{
  flake-file.inputs = {
    nixpkgs.url = "github:nixos/nixpkgs/nixpkgs-unstable";
  };
}
```

--------------------------------

### Specify modules for flake generation

Source: https://github.com/denful/flake-file/blob/main/docs/src/content/docs/reference/bootstrap.mdx

Use the `modules` argument to point to a Nix file or directory containing your flake module definitions. All `.nix` files in a specified directory are automatically imported.

```shell
# Single file
--arg modules ./flake-file.nix
```

```shell
# Directory (all .nix files imported)
--arg modules ./modules
```

--------------------------------

### Daily Workflow Commands for flake-file

Source: https://context7.com/denful/flake-file/llms.txt

Common commands for managing flake.nix, npins, unflake, and nixlock files.

```shell
# Regenerate flake.nix from module declarations
nix run .#write-flake

# Check that flake.nix is in sync with modules (add to CI)
nix flake check

# Regenerate npins/ (non-flake backend)
nix run .#write-npins

# Regenerate unflake.nix (non-flake backend)
nix run .#write-unflake

# Regenerate nixlock.lock.nix (non-flake backend)
nix run .#write-nixlock

# Auto-detect existing lock type and regenerate accordingly
nix run .#write-lock

# Debug: dump the merged inputs expression without writing
nix run .#write-inputs
```

--------------------------------

### Generating unflake.nix or nixlock.lock.nix

Source: https://context7.com/denful/flake-file/llms.txt

Commands to write `unflake.nix` or `nixlock.lock.nix` using `flake-file.sh`. These commands can be executed from a Nix shell or a bootstrapped flake.

```shell
# Write unflake.nix
nix-shell https://github.com/vic/flake-file/archive/main.tar.gz \
  -A flake-file.sh --run write-unflake --arg modules ./flake-file.nix

# Write nixlock.lock.nix
nix-shell https://github.com/vic/flake-file/archive/main.tar.gz \
  -A flake-file.sh --run write-nixlock --arg modules ./flake-file.nix

```

--------------------------------

### Add flake-file input to flake.nix

Source: https://github.com/denful/flake-file/blob/main/docs/src/content/docs/tutorials/migrate.mdx

Add the flake-file input to your existing flake.nix file. This makes flake-file available for use in your project.

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

--------------------------------

### Enable in-flake flake-file app

Source: https://github.com/denful/flake-file/blob/main/docs/src/content/docs/tutorials/migrate-flake-parts.mdx

Modify modules/inputs.nix to include flake-file as a dependency and enable its flake module for in-flake functionality.

```nix
# modules/inputs.nix
+ { inputs, lib, ... }: # resolved flake inputs as specialArgs
  {
    # same inputs code as before
    flake-file.inputs = {

      # make sure you add flake-file dependency.
+     flake-file.url = lib.mkDefault "github:vic/flake-file";
    };

    imports = [
       # enable inside-flake and say goodbye to bootstrap
+      inputs.flake-file.flakeModules.default

       # start splitting from inputs.nix into other files
    ];

    # generate the same output function we used at bootstrap
+   flake-file.outputs = "flake-parts";
  }
```

--------------------------------

### Update flake.nix after Input Changes

Source: https://github.com/denful/flake-file/blob/main/docs/src/content/docs/tutorials/migrate-traditional-flake.mdx

When your flake inputs change, re-run the bootstrap command to update the static `flake.nix` file. This ensures that the generated `flake.nix` reflects the latest input states.

```shell
nix-shell https://github.com/vic/flake-file/archive/main.zip -A flake-file.sh --run bootstrap
```

--------------------------------

### Bootstrap npins from flake-file.nix

Source: https://github.com/denful/flake-file/blob/main/docs/src/content/docs/tutorials/migrate-no-flakes.mdx

Use the flake-file.sh script to generate or update the ./npins file based on the definitions in flake-file.nix. Ensure to back up any existing ./npins directory before running.

```shell
nix-shell https://github.com/vic/flake-file/archive/main.tar.gz \n  -A flake-file.sh --run write-npins --arg modules ./flake-file.nix
```

--------------------------------

### Separate Outputs Function in flake.nix

Source: https://github.com/denful/flake-file/blob/main/docs/src/content/docs/explanation/what-is-flake-file.mdx

Move your outputs function into a separate file (e.g., `outputs.nix`) and import it into `flake.nix`. This promotes a cleaner separation of concerns, treating `flake.nix` primarily as a dependency manifest.

```nix
# flake.nix
{
   inputs = { };
   outputs = inputs: import ./outputs.nix inputs;
}
```

--------------------------------

### Define Output Schema in flake-file.nix

Source: https://github.com/denful/flake-file/blob/main/docs/src/content/docs/tutorials/migrate-traditional-flake.mdx

Add an output schema to your `flake-file.nix` to validate the 'hello' attribute. This schema uses Nix's module system for validation, requiring no custom Nix implementations.

```nix
# flake-file.nix
{
  outputs = inputs: { hello = "mundo"; };

  flake-file.outputs-schema = { lib, ... }:
    {
      options.hello = lib.mkOption {
        type = lib.types.enum [ "mundo" ];
      };
    };
}
```

--------------------------------

### Update nixlock.lock.nix

Source: https://github.com/denful/flake-file/blob/main/templates/nixlock/README.md

Run this command to update the nixlock.lock.nix file, fetching the latest input versions. This is useful when dependencies change.

```shell
nix-shell . -A flake-file.sh --run 'write-nixlock update'
```

--------------------------------

### Move outputs to outputs.nix

Source: https://github.com/denful/flake-file/blob/main/docs/src/content/docs/tutorials/migrate.mdx

Copy the body of your flake.nix's outputs function into a new file named outputs.nix. This separates the main flake logic from input declarations.

```nix
# outputs.nix
inputs: inputs.flake-parts.lib.mkFlake { inherit inputs; } {
  imports = [
    ./modules/inputs.nix
    # Add more modules here as you split things up.
  ];
}
```

--------------------------------

### Declare Inputs in a Flake Module

Source: https://context7.com/denful/flake-file/llms.txt

Declare inputs for a flake module. Use `lib.mkDefault` for optional inputs.

```nix
{ inputs, lib, ... }:
{
  flake-file.inputs = {
    flake-file.url  = lib.mkDefault "github:vic/flake-file";
    flake-parts.url = "github:hercules-ci/flake-parts";
    nixpkgs.url     = "github:nixos/nixpkgs/nixpkgs-unstable";
  };

  # Enable the in-flake write-flake app
  imports = [ inputs.flake-file.flakeModules.default ];

  flake-file.outputs = "flake-parts";
}
```

--------------------------------

### Use Generated npins in Default Nix

Source: https://context7.com/denful/flake-file/llms.txt

Import and use the generated npins file as inputs in a default.nix file.

```nix
let
  sources = import ./npins;
  nixpkgs  = import sources.nixpkgs { };
  outputs  = (nixpkgs.lib.evalModules {
    modules   = [ (import ./modules) ];
    specialArgs = { inputs = sources; };
  }).config;
in outputs
```

--------------------------------

### Daily commands for flake-file

Source: https://github.com/denful/flake-file/blob/main/docs/src/content/docs/tutorials/migrate-flake-parts.mdx

Commands to regenerate flake.nix and check flake integrity after enabling flake-file.

```shell
nix run .#write-flake # whenever you need to regen flake.nix
```

```shell
nix flake check # will make sure your flake.nix is up-to-date
```

--------------------------------

### Generated flake.nix Structure

Source: https://github.com/denful/flake-file/blob/main/docs/src/content/docs/guides/outputs.mdx

Illustrates where the value of `flake-file.outputs` is placed in the generated `flake.nix` file.

```nix
{ 
  outputs = <your flake-file.outputs value here>;
}
```

--------------------------------

### Run Astro CLI Commands

Source: https://github.com/denful/flake-file/blob/main/docs/README.md

Execute various Astro command-line interface commands, such as adding integrations or checking your project.

```bash
pnpm astro ...
```

--------------------------------

### Control auto-generated header and formatter

Source: https://context7.com/denful/flake-file/llms.txt

Customize the "do not edit" banner comment and specify a formatter for the output `flake.nix` file.

```nix
# modules/style.nix
{ pkgs, ... }:
{
  # Custom "do not edit" banner at the top of the generated flake.nix
  flake-file.do-not-edit = ''
    # !! THIS FILE IS AUTO-GENERATED — edit modules/*.nix instead !!
    # Run: nix run .#write-flake
  '';

  # Apply nixfmt-rfc-style after writing
  flake-file.formatter = pkgs: pkgs.nixfmt-rfc-style;
}
```

--------------------------------

### Update default.nix for modularity

Source: https://github.com/denful/flake-file/blob/main/docs/src/content/docs/tutorials/migrate-no-flakes.mdx

Modify the default.nix to import the new inputs.nix and use Nix Modules. This version integrates the inputs defined in modules/inputs.nix.

```nix
# modules/default.nix
{ inputs, lib, ... }:
let
  sources = import ./npins;
in
{
  imports = [ ./inputs.nix ];

  nixosConfigurations.my-laptop = ...; # use inputs
}
```

--------------------------------

### Include predefined bootstrap inputs

Source: https://github.com/denful/flake-file/blob/main/docs/src/content/docs/reference/bootstrap.mdx

The `bootstrap` argument controls which predefined inputs are included in the generated flake. Set to `true` to include all, or provide a list of specific input names.

```shell
# Include all bootstrap inputs
--arg bootstrap true
```

```shell
# Include only specific ones
--arg bootstrap '["flake-file" "nixpkgs"]'
```

--------------------------------

### Configure attribute sorting and separators

Source: https://context7.com/denful/flake-file/llms.txt

Control the ordering of attributes and the whitespace separators used in the generated `flake.nix` file.

```nix
# modules/style.nix
{ ... }:
{
  # Custom separator between top-level flake attributes (default: newline)
  flake-file.style.sep.flake      = "\n";
  flake-file.style.sep.inputs     = "\n";
  flake-file.style.sep.inputSchema = "\n";
  flake-file.style.sep.nixConfig  = "\n";

  # Pin inputs sort order: listed names come first, rest are alphabetical
  flake-file.style.sortPriority.inputs = [
    "nixpkgs"
    "flake-parts"
    "flake-file"
  ];

  # Pin flake top-level sort order
  flake-file.style.sortPriority.flake = [
    "description"
    "nixConfig"
    "inputs"
    "outputs"
  ];
}
```