# 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

```bash
nix flake show --templates .
```

### 2. Initialize from a Template

```bash
# 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:

```bash
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

```nix
# 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](./guides/adding-packages.md) 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](./guides/adding-packages.md) - Detailed package guide
- [Adding Modules](./guides/adding-modules.md) - Detailed module guide
- [Development Workflow](./guides/development-workflow.md) - Local development
- [Architecture](./ARCHITECTURE.md) - Repository structure