AGENT.md

This file provides guidance to coding agents when working with code in this repository.

Repository Overview

This is a collection of Nix flake templates for various programming languages and development scenarios. Each template provides a development shell with language-specific tooling and optionally formatters, linters, and build configurations.

Architecture

Root flake.nix: Defines all available templates with their paths and descriptions
Template directories: Each subdirectory contains a complete flake.nix for a specific use case
Documentation site: Located in
```
/doc
```
, built with Astro and Starlight
Development utilities: Located in
```
/dev
```
, contains maintenance tools

Template Categories

Minimal templates:
```
minimal
```
,
```
flake-utils
```
,
```
flake-parts
```
- Basic boilerplates
Language-specific:
```
rust
```
,
```
go
```
,
```
python-uv-simple
```
,
```
elixir
```
,
```
gleam
```
,
```
zig
```
, etc.
Web development:
```
node-typescript
```
,
```
typescript-effect
```
OCaml:
```
ocaml-basic
```
,
```
ocaml-dune
```
Tooling:
```
pre-commit
```
,
```
treefmt
```
- Development workflow tools
Metadata:
```
meta
```
- GitHub project files

Common Development Commands

Documentation Site (in

/doc

)

# Install dependencies
pnpm install

# Development server
pnpm dev

# Build site
pnpm build

# Type check
astro check

Code Formatting

# Format Nix files (repository-wide)
nix fmt

# Format using treefmt configuration
treefmt

Flake Operations

# Test all templates
nix flake check

# Initialize a project with a template
nix flake init -t github:akirak/flake-templates#<template-name>

# List all available templates
nix flake show

Development Environment

# Enter development shell
nix develop

# For documentation work
cd doc && nix develop

Key Design Principles

Templates assume no non-Nix dependencies (work on any Nix-supported platform)
Each template provides minimal viable development environment
Language servers and formatters included where applicable
Templates complement language scaffolding tools rather than replace them
flake-parts used where it makes configuration more concise

Template Structure Patterns

Most templates follow this pattern:

```
flake.nix
```
: Main flake configuration
Language-specific config files (e.g.,
```
treefmt.nix
```
,
```
tsconfig.json
```
)
Optional: justfile, package.json, or other build configuration
Each language-specific template should have at least one corresponding documentation in
```
/doc
```

Special Templates

typescript-effect: Opinionated setup with Effect-TS, ESLint, lefthook
elixir-app: Complex setup with Phoenix dependencies, process-compose integration
ocaml-dune: Integrates with nix-ocaml overlay for package building
rust: Uses crane and rust-overlay for deterministic builds
treefmt: Demonstrates formatter configuration patterns

Testing Templates

When modifying templates, test them by:

Initialize in a temporary directory:
```
nix flake init -t .#<template>
```
Enter development shell:
```
nix develop
```
Verify language tools are available
Run any included formatters/linters

Documentation

Documentations should be specific to project types
Link to each documentation from
```
/doc/astro.config.mjs
```

Architecture

Root flake.nix: Defines all available templates with their paths and descriptions

Template directories: Each subdirectory contains a complete flake.nix for a specific use case

Documentation site: Located in

/doc

, built with Astro and Starlight

Development utilities: Located in

/dev

, contains maintenance tools

Minimal templates:

minimal

flake-utils

flake-parts

- Basic boilerplates

Language-specific:

rust

go

python-uv-simple

elixir

gleam

zig

, etc.

Web development:

node-typescript

typescript-effect

OCaml:

ocaml-basic

ocaml-dune

Tooling:

pre-commit

treefmt

- Development workflow tools

Metadata:

meta

- GitHub project files

Common Development Commands

# Install dependencies
pnpm install

# Development server
pnpm dev

# Build site
pnpm build

# Type check
astro check

# Format Nix files (repository-wide)
nix fmt

# Format using treefmt configuration
treefmt

# Test all templates
nix flake check

# Initialize a project with a template
nix flake init -t github:akirak/flake-templates#<template-name>

# List all available templates
nix flake show

# Enter development shell
nix develop

# For documentation work
cd doc && nix develop

Key Design Principles

Templates assume no non-Nix dependencies (work on any Nix-supported platform)

Each template provides minimal viable development environment

Language servers and formatters included where applicable

Templates complement language scaffolding tools rather than replace them

flake-parts used where it makes configuration more concise

Special Templates

typescript-effect: Opinionated setup with Effect-TS, ESLint, lefthook

elixir-app: Complex setup with Phoenix dependencies, process-compose integration

ocaml-dune: Integrates with nix-ocaml overlay for package building

rust: Uses crane and rust-overlay for deterministic builds

treefmt: Demonstrates formatter configuration patterns

AGENT.md

AGENT.md

Repository Overview

Architecture

Template Categories

Common Development Commands

Documentation Site (in
`/doc`
)

Code Formatting

Flake Operations

Development Environment

Key Design Principles

Template Structure Patterns

Special Templates

Testing Templates

Documentation

Related Skills

Markdown Converter

Nano Banana Pro

1password

AGENT.md

Repository Overview

Architecture

Template Categories

Common Development Commands

Documentation Site (in
`/doc`
)

Code Formatting

Flake Operations

Development Environment

Key Design Principles

Template Structure Patterns

Special Templates

Testing Templates

Documentation