nixpkgs/docs/templates.md

Templates

Boilerplate templates for quickly adding new packages or modules to m3ta-nixpkgs.

Available Templates

Template	Command	Creates
Package	nix flake init -t .#package	templates/package/
NixOS Module	nix flake init -t .#nixos-module	templates/nixos-module/
Home Manager Module	nix flake init -t .#home-manager-module	templates/home-manager-module/

Using Templates

1. List Available Templates

nix flake show --templates .

2. Initialize from a Template

# Package
nix flake init -t .#package

# NixOS Module
nix flake init -t .#nixos-module

# Home Manager Module
nix flake init -t .#home-manager-module

Note: nix flake init copies the template contents into the current directory. Use a subdirectory name:

mkdir new-package && cd new-package
nix flake init -t ..#package

Package Template

Creates a complete package structure:

templates/package/
├── default.nix    # Package definition with comments

Fields to Fill In

Field	Location	Notes
pname	default.nix	Package name (kebab-case)
version	default.nix	Semantic version
src	default.nix	Fetcher (GitHub, URL, Git, etc.)
hash	default.nix	Use lib.fakeHash, build to get real hash
meta.description	default.nix	Short one-line description
meta.homepage	default.nix	Project URL
meta.license	default.nix	Use lib.licenses.*
meta.platforms	default.nix	Usually platforms.linux
meta.mainProgram	default.nix	Main binary name

Common Build Systems

# Rust (recommended)
rustPlatform.buildRustPackage rec { ... }

# Python
python3.pkgs.buildPythonPackage rec { ... }

# Node.js
pkg-config, nodejs, npm2nix, or pnpm + prisma

# Shell script
writeShellScriptBin "name" ''echo hello''

# Go
go mdbook build

# Generic C/Make
stdenv.mkDerivation { ... }

See Adding Packages for detailed instructions.

NixOS Module Template

Creates a complete NixOS module:

templates/nixos-module/
├── default.nix    # Module with options
└── README.md       # Module documentation

Fields to Fill In

Field	Location	Notes
Module name	default.nix	File name matches m3ta.<name>
Options	default.nix	Add under options.m3ta.<name>
Config	default.nix	Add under config.m3ta.<name>
Description	README.md	What the module does

After Creating

1. Add to modules/nixos/default.nix imports
2. Optionally export from flake.nix nixosModules
3. Add documentation to docs/modules/nixos/
4. Run nix flake check

Home Manager Module Template

Creates a complete Home Manager module:

templates/home-manager-module/
├── default.nix    # Module with options
└── README.md       # Module documentation

Fields to Fill In

Field	Location	Notes
Category	Directory	Choose cli/ or coding/
Options	default.nix	Add under options.m3ta.<name>
Config	default.nix	Add under config.m3ta.<name>
Description	README.md	What the module does

After Creating

1. Add to the appropriate category aggregator (cli/default.nix or coding/default.nix)
2. Optionally export from flake.nix homeManagerModules
3. Add documentation to docs/modules/home-manager/
4. Run nix flake check

Template Variables

Templates use Nix attribute references. After copying, search for these placeholders:

Placeholder	Replace With
package-name	Your package name (kebab-case)
owner-name / repo-name	GitHub owner and repo
0.1.0	Initial version
lib.fakeHash	Real hash after first build
lib.licenses.mit	Appropriate license
A short description	One-line description

Automated Updates

Packages created from templates are automatically updated weekly by the Gitea Actions workflow. See the main README for details on the nix-update automation.

Related

• Adding Packages - Detailed package guide
• Adding Modules - Detailed module guide
• Development Workflow - Local development
• Architecture - Repository structure