{"id":29644080,"url":"https://github.com/tsandrini/flake-parts-builder","last_synced_at":"2026-04-30T03:50:11.203Z","repository":{"id":208271709,"uuid":"721191542","full_name":"tsandrini/flake-parts-builder","owner":"tsandrini","description":"Nix flakes interactive template builder based on flake-parts written in Rust. [maintainer=@tsandrini]","archived":false,"fork":false,"pushed_at":"2025-11-24T18:54:54.000Z","size":389,"stargazers_count":47,"open_issues_count":14,"forks_count":2,"subscribers_count":2,"default_branch":"main","last_synced_at":"2026-04-30T03:49:31.664Z","etag":null,"topics":["flakes","nix","nix-flake","nix-flakes","nix-template","nix-templates","nixos-configuration","nixos-flake","rust"],"latest_commit_sha":null,"homepage":"","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/tsandrini.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2023-11-20T14:42:53.000Z","updated_at":"2026-03-12T11:26:25.000Z","dependencies_parsed_at":"2024-03-04T15:57:57.372Z","dependency_job_id":"d1f6dc20-a3f0-43c7-9067-7a632eefdc5c","html_url":"https://github.com/tsandrini/flake-parts-builder","commit_stats":null,"previous_names":["tsandrini/practical-flakes-template"],"tags_count":5,"template":false,"template_full_name":null,"purl":"pkg:github/tsandrini/flake-parts-builder","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tsandrini%2Fflake-parts-builder","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tsandrini%2Fflake-parts-builder/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tsandrini%2Fflake-parts-builder/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tsandrini%2Fflake-parts-builder/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tsandrini","download_url":"https://codeload.github.com/tsandrini/flake-parts-builder/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tsandrini%2Fflake-parts-builder/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32454170,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-29T22:27:22.272Z","status":"online","status_checked_at":"2026-04-30T02:00:05.929Z","response_time":57,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["flakes","nix","nix-flake","nix-flakes","nix-template","nix-templates","nixos-configuration","nixos-flake","rust"],"created_at":"2025-07-22T00:02:39.072Z","updated_at":"2026-04-30T03:50:07.453Z","avatar_url":"https://github.com/tsandrini.png","language":"Rust","funding_links":[],"categories":["Related Patterns, Frameworks, Utilities and Libraries"],"sub_categories":["Community Modules"],"readme":"# flake-parts-builder\n\n[![flake check](https://github.com/tsandrini/flake-parts-builder/actions/workflows/flake-check.yml/badge.svg)](https://github.com/tsandrini/flake-parts-builder/actions/workflows/flake-check.yml)\n[![FlakeHub](https://github.com/tsandrini/flake-parts-builder/actions/workflows/flakehub-publish.yml/badge.svg)](https://github.com/tsandrini/flake-parts-builder/actions/workflows/flakehub-publish.yml)\n[![cachix](https://github.com/tsandrini/flake-parts-builder/actions/workflows/cachix-push.yml/badge.svg)](https://github.com/tsandrini/flake-parts-builder/actions/workflows/cachix-push.yml)\n[![flake.lock update](https://github.com/tsandrini/flake-parts-builder/actions/workflows/update-flake-lock.yml/badge.svg)](https://github.com/tsandrini/flake-parts-builder/actions/workflows/update-flake-lock.yml)\n\n## 1. About 📝\n\nBuilding a new [flake-parts](https://github.com/hercules-ci/flake-parts) project?\nNeed a template with all the necessary boilerplate, but none perfectly fits your\nneeds? Just choose the parts that you need and **build your own**!\n\n```bash\nnix run github:tsandrini/flake-parts-builder -- init -p +github,+nixos,treefmt myNewProject\n```\n\n-----\n\nTemplates defined to be used with `nix flake init -t` typically suffer from\nthe case of being **static** and too simple. They usually address only one\nspecific thing or problem domain (eg. devenv, rust, flake-parts, dotfiles, ...)\nwhich makes the end user quickly start running into issues  when trying to\ncombine said domains since real life flake projects rarely require only one\nsuch domain.\n\nAnd this is what `flake-parts-builder` solves! It serves as a\n**dynamic extension** to `nix flake init -t`, nothing more, nothing less!\nSo let's forget about `nix flake init -t` and embrace `nix run` instead :sunglasses:\n\n-----\n\nOkay, but what exactly does it do then?\n\n- `flake-parts-builder init` - **initialize** a new project with all your\n  required parts\n- `flake-parts-builder add` - **add** new parts to an already existing\n  flake-parts project\n- `flake-parts-builder list` - **list** all currently available flake-parts to\n  be used with the `list` and `add` subcommands\n\n## 2. Installation 🤖\n\n**Disclaimer**: `flake-parts-builder` is built on top of nix\n[flakes](https://wiki.nixos.org/wiki/Flakes) and\n[flake-parts](https://github.com/hercules-ci/flake-parts) hence why familiarity\nwith flakes is a necessity. The builder also currently runs in flakes mode only\nand uses flakes to parse flake-parts stores. The following \"experimental\"\nfeatures are then a forced requirement\n`--experimental-features 'nix-command flakes'`.\n\n*NOTE*: if enough people will be using this project I don't have any issues\nwith pushing it into upstream  [nixpkgs](https://github.com/NixOS/nixpkgs).\n\n### 2.1. Nix CLI\n\n```bash\nnix profile install github:tsandrini/flake-parts-builder\n```\n\n### 2.2. NixOS\n\n```nix\n{\n  inputs.flake-parts-builder.url = \"github:tsandrini/flake-parts-builder\";\n\n  outputs = { self, nixpkgs, flake-parts-builder }: {\n    # change `yourhostname` to your actual hostname\n    nixosConfigurations.yourhostname = nixpkgs.lib.nixosSystem {\n      # change to your system:\n      system = \"x86_64-linux\";\n      modules = [\n        ./configuration.nix\n        ({ system, ... }: {\n           environment.systemPackages = [ flake-parts-builder.packages.${system}.default ];\n        })\n      ];\n    };\n  };\n}\n```\n\n### 3. Binary cache 💾\n\n`flake-parts-builder` is written in Rust with minimal dependencies to ensure\nsafety and consistency, however, there is also a binary cache available if you'd\nlike to skip the build process. \n\n```nix\n  nixConfig = {\n    extra-substituters = [\n      \"https://tsandrini.cachix.org\"\n    ];\n    extra-trusted-public-keys = [\n      \"tsandrini.cachix.org-1:t0AzIUglIqwiY+vz/WRWXrOkDZN8TwY3gk+n+UDt4gw=\"\n    ];\n  };\n```\n\n## 4. Available parts 📂\n\nYou can list all of the available parts with the `flake-parts-builder list`\nsubcommand, which goes through all of the flake-parts stores passed via the `-I`\nor `--include` flag. Here is the current output the list subcommand running on\nonly the base parts provided by this flake (note that you can disable the base\nparts using `--disable-base` if you wish so)\n\n```bash\nflake-parts-builder list\n```\n\n```md\n # github:tsandrini/flake-parts-builder#flake-parts\n  - +github: (Collection) GitHub related parts\n  - +home-manager: (Collection) Home-manager related parts.\n  - +nixos: (Collection) NixOS related parts.\n  - +nixvim: (Collection) All of the nixvim related parts.\n  - agenix: Bindings for the agenix secrets manager with prepared NixOS/HM modules ready to be used in your configurations.\n  - deploy-rs: A Simple multi-profile Nix-flake deploy tool.\n  - devenv: Flake bindings for the `github:cachix/devenv` development environment.\n  - flake-root: Provides `config.flake-root` variable pointing to the root of the flake project.\n  - gh-actions-cachix: Adds a simple cachix/cachix-action GitHub action workflow.\n  - gh-actions-check: Adds a simple `nix flake check` GitHub action workflow.\n  - gh-actions-flake-update: Adds the periodic `DeterminateSystems/update-flake-lock` GitHub action workflow.\n  - gh-actions-flakehub: Adds the push to FlakeHub GitHub action workflow.\n  - gh-actions-pages: Adds a GitHub action that runs `nix build .#pages` and deploys the result to GitHub pages.\n  - gh-dependabot: A basic GitHub dependabot starting template.\n  - gh-templates-PR: Adds a basic GitHub pull request template.\n  - gh-templates-issues: Adds basic bug/feature GitHub issue templates.\n  - gitlab-ci-check: Adds a simple `nix flake check` to your GitLab CI/CD pipeline.\n  - hm-homes: Template for your HM homes and a handy generator for you `homeManagerConfiguration` calls.\n  - hm-modules: Basic template for custom home-manager modules.\n  - lib: Basic template for custom nix library functions.\n  - nix-topology: Adds bindings for the `github:oddlama/nix-topology` project to generate graphs of your networks.\n  - nixos-hosts: Template for your NixOS hosts and a handy generator for `lib.nixosSystem` calls.\n  - nixos-modules: Basic template for custom NixOS modules.\n  - nixvim-configurations: Template for Nixvim configurations to handle multiple neovim instances.\n  - nixvim-modules: Basic template for reusable nixvim modules.\n  - overlays: Basic template for custom nixpkgs overlays.\n  - pkgs: Basic template for custom nix packages (ie derivations).\n  - pre-commit-hooks: Bindings for pre-commit-hooks.nix and a simple pre-commit-hook template.\n  - process-compose-flake: Bindings for process-compose-flake and a simple process-compose template.\n  - shells: Basic template for custom nix devshells (ie. `mkShell` calls) with potential bindings to other parts.\n  - systems: Sets up the default `systems` of flake-parts using `github:nix-systems/default`.\n  - treefmt: Bindings for the treefmt formatter and a basic treefmt configuration.\n\n # github:tsandrini/flake-parts-builder#flake-parts-bootstrap\n  - _bootstrap: (Required) Minimal set of functions used to bootstrap your flake-parts project.\n```\n\n## 6. `flake-parts-builder.lib` API\n\nIf you'd like to remove the `./flake-parts/_bootstrap.nix` file or you'd prefer\nusing any of the flake-parts functionality in a different set of circumstances \nthen you can use the `flake-parts-builder.lib` output that this repo exposes. You could \nthen rewrite your `flake.nix` in the following manner (this, however, adds an\nadditional  dependency to your project)\n\n```nix\n# --- flake.nix\n{\n  inputs = {\n    # --- BASE DEPENDENCIES ---\n    nixpkgs.url = \"github:nixos/nixpkgs/nixos-unstable\";\n    flake-parts.url = \"github:hercules-ci/flake-parts\";\n    flake-parts-builder.url = \"github:tsandrini/flake-parts-builder\";\n\n    # --- (YOUR) EXTRA DEPENDENCIES ---\n  };\n\n  outputs =\n    inputs@{ flake-parts, ... }:\n    let\n      inherit (inputs.nixpkgs) lib;\n      inherit (inputs.flake-parts-builder.lib) loadParts;\n    in\n    flake-parts.lib.mkFlake { inherit inputs; } {\n      imports = loadParts ./flake-parts;\n    };\n}\n```\n\nFor more info regarding the API of any of these functions, please refer to the \ndoccomments of said functions in the `flake.nix` file.\n\n## 7. Using your own parts 👨‍💻👩‍💻\n\n`flake-parts-builder` was designed from the ground up with extensibility in mind.\nTo be able to use local parts, remote parts and cache parts in an easy manner\nthe CLI accepts additional flake-parts stores via the `-I` or `--include` flag\nas flake derivation outputs. Meaning that you can run\n\n```bash\nflake-parts-builder init -I ./myDir#flake-parts -p shells,pkgs,my-custom-part myNewProject\n```\n\nor even remote parts stores\n\n```bash\nflake-parts-builder init -I github:org/my-flake-project#flake-parts -p shells,my-custom-remote-part myNewProject\n```\n\nThanks to the wonders of nix, the flake-parts stores will be resolved \u0026 fetched\nonly once and on successive calls, they will be copied directly from you local\n`/nix/store` cache.\n\n### 7.1. Custom flake-parts-stores\n\nA **flake-part store** is any derivation that has **flake-parts** located at\n`$out/flake-parts`, so for example the following snippet\n\n```nix\nstdenv.mkDerivation {\n  name = \"my-custom-flake-parts\";\n  version = \"1.0.0\";\n  src = ./flake-parts;\n\n  dontConfigure = true;\n  dontBuild = true;\n  dontCheck = true;\n\n  installPhase = ''\n    mkdir -p $out/flake-parts\n    cp -rv $src/* $out/flake-parts\n  '';\n}\n```\n\nThis flake also exposes a handy wrapper at `flake-parts-builder.lib.mkFlakeParts`,\nwhich shortens the previous example to\n\n```nix\nmkFlakeParts {\n  inherit stdenv; # NOTE: Required\n  name = \"my-custom-flake-parts\";\n  version = \"1.0.0\";\n  src = ./flake-parts;\n}\n```\n\n### 7.2. Custom flake-parts \n\nA **flake-part** is any folder with a **meta.nix** file at its root containing\nan attrset with the following structure.\n\n```nix\n{\n  description = \"Flake bindings for the cachix/devenv development environment.\";\n\n  inputs = {\n    devenv.url = \"github:cachix/devenv\"\n    # ....\n  };\n  dependencies = [ ];\n  conflicts = [ \"shells\" ];\n  extraTrustedPublicKeys = [ \"devenv.cachix.org-1:w1cLUi8dv3hnoSPGAuibQv+f9TZLr6cv/Hm9XgU50cw=\" ];\n  extraSubstituters = [ \"https://devenv.cachix.org\" ];\n}\n```\n\n- `description`: a simple description of the provided parts printed when running\n  `flake-parts-builder list`\n- `inputs`: flake inputs that will be recursively merged from all required parts\n  and pasted into the final `flake.nix` file\n- `dependencies`: with this you can add any additional required parts for the\n  initialization/addition, this can be either a full flake uri (eg.\n  `github:org/my-flake-project#flake-parts/my-custom-flake-part`) or a local\n  reference to some other part **included in the same flake-parts store**\n  (eg. `my-custom-part`)\n- `conflicts`: a specification of other potentially conflicting parts \n  (for example when handling the same functionality, like `devenv` and `shells`)\n  that should abort the process in case of found conflict, note that you can\n  force the initialization/addition even in case of conflict with the\n  `--ignore-conflicts`\n- `extraTrustedPublicKeys`: merged with all of the required parts and pasted into\n  the final `flake.nix`, for security purposes they are all commented out\n- `extraSubstituters`: merged with all of the required parts and pasted into the\n  final `flake.nix`, for security purposes they are all commented out\n\n## 8. Additional questions, issues 🗣️\n\n### 8.1. How can I use a custom version of the `nix` or `nixfmt` binary?\n\nIf installed via the nix package manager, `flake-parts-builder` will use\nan isolated version of `pkgs.nixVersions.stable` with\n`--extra-experimental-features 'nix-command flakes'` enabled. However, if you'd\nlike to use a custom version instead, simply pass it via `$NIX_BIN_PATH`,\nfor example\n\n```bash\nNIX_BIN_PATH=/bin/patched-nix flake-parts-builder init -p +home-manager,shells myNewProject\n```\n\nThe same thing works for overriding the `nixfmt` binary using the \n`NIXFMT_BIN_PATH` environment variable\n\n```bash\nNIXFMT_BIN_PATH=/bin/nixfmt-classic flake-parts-builder init -p +home-manager,shells myNewProject\n```\n\n### 8.2. Why not use `flake.templates` instead?\n\nThe `flake.templates` flake output is a static property by design that needs\nto point to a fixed path with fixed content known ahead of time, which makes\nit heavily impractical for any kind of dynamic evaluation. One could,\ngiven the set of parts, prepare all of the possible combinations of templates\nwith some patching script and\ndirectly update the source code of `flake.nix`, however ... At the time of\nthis writing there are currently $27+1$ flake parts provided by this flake in\nthe base collection of parts, which would result in\n\n```math\n2^{28} - 1 = 268435455\n```\n\ntotal combinations of templates and with an average part size of\n$8.59 \\pm 2.60$ KB this would result in $2.14$ total terabytes of data\nwith just one part per template. :skull:\n\nI hope this is enough of an answer.\n\n### 8.3. Can't we just stuff this functionality into `flakeModules`?\n\nI totally agree there is a fine line between a reusable piece of functionality\nand boilerplate template code and I personally can't think of a general enough\ndefinition that would discern them and also be somehow useful. However, I do\nbelieve there is a practical, clearly visible difference between them that most\nprogrammers can just simply look and see, let's for example take ....\n[devenv/dev.nix](flake-parts/devenv/flake-parts/devenv/dev.nix) or\n[nix-topology/topology.nix](flake-parts/nix-topology/flake-parts/nix-topology/topology.nix)\nor even\n[flake-check.yml](flake-parts/gh-actions-check/.github/workflows/flake-check.yml),\nyou can clearly **\"see\"** that this isn't a good candidate for a `flakeModule`,\nthey are too specific, they typically represent the end user options of some\nexisting `flakeModule`s. Wrapping this code into another layer of modularity\ndoesn't make sense, since this is meant to be a piece of configuration code.\n\n### 8.4. Help! I'm experiencing an XYZ bug!\n\nI'm sorry for the inconvenience, please run whatever is producing said bug\nwith these `RUST_LOG=debug RUST_BACKTRACE=full` environment variables, \nfor example\n\n``` bash\nRUST_LOG=debug RUST_BACKTRACE=full flake-parts-builder add shells ./myProject\n```\n\nand paste the output into a new bug issue. Thanks! :heart:\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftsandrini%2Fflake-parts-builder","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftsandrini%2Fflake-parts-builder","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftsandrini%2Fflake-parts-builder/lists"}