Skip to content

AGENTS.md

Latest commit

 

History

History
116 lines (85 loc) · 3.54 KB

AGENTS.md

File metadata and controls

116 lines (85 loc) · 3.54 KB

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

  1. Minimal templates: minimal, flake-utils, flake-parts - Basic boilerplates
  2. Language-specific: rust, go, python-uv-simple, elixir, gleam, zig, etc.
  3. Web development: node-typescript, typescript-effect
  4. OCaml: ocaml-basic, ocaml-dune
  5. Tooling: pre-commit, treefmt - Development workflow tools
  6. 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

Licensing

  • Add SPDX license headers to every file that supports comments.
  • Ensure every file in the repository is covered by REUSE.toml, including files that cannot contain license headers.
  • When adding, moving, or deleting files, update REUSE.toml in the same change so REUSE coverage remains complete.

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:

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

Documentation

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