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