Getting started

Welcome to nix-config! This guide will help you get started with this NixOS and nix-darwin configuration repository.

Prerequisites

Before you begin, ensure you have:

• Nix with flakes enabled
• direnv (recommended for automatic shell activation)
• Git for version control
• A GitHub account (for CI/CD features)

Enabling Nix flakes

If you haven’t enabled flakes yet, add this to ~/.config/nix/nix.conf:

experimental-features = nix-command flakes

Or for NixOS, add to /etc/nixos/configuration.nix:

nix.settings.experimental-features = [ "nix-command" "flakes" ];

Quick setup

1. Get the template

Choose one of these methods:

Option A: Use as GitHub template

# Click "Use this template" on GitHub, then:
git clone https://github.com/YOUR_USERNAME/YOUR_REPO.git
cd YOUR_REPO

Option B: Fork manually

git clone https://github.com/cameronraysmith/infra.git my-project
cd my-project
rm -rf .git
git init

2. Enter the development environment

# Allow direnv (recommended)
direnv allow

# Or enter manually
nix develop

The first time may take a few minutes as Nix downloads dependencies.

3. Install JavaScript dependencies

bun install

4. Start development server

just dev

Visit http://localhost:4321 to see your site.

Understanding the structure

This is a Bun workspace monorepo:

nix-config/
├── packages/
│   └── docs/                 # Astro Starlight documentation
│       ├── src/             # Source code
│       ├── e2e/             # End-to-end tests
│       ├── tests/           # Unit test fixtures
│       └── package.json     # Package configuration
├── package.json             # Workspace root
├── flake.nix                # Nix development environment
├── justfile                 # Task automation
└── CONTRIBUTING.md          # Contribution guidelines

See Architecture decisions for design rationale.

Essential commands

Development

# Start dev server
just dev

# Build for production
just build

# Preview production build
just preview

Testing

# Run all tests
just test

# Run unit tests only
just test-unit

# Run E2E tests only
just test-e2e

# Watch mode
just test-watch

See Testing guide for comprehensive documentation.

Code quality

# Format code
just format

# Lint code
just lint

# Check and fix
just check

Nix environment

# Rebuild flake
nix flake check --impure

# Show flake info
nix flake show

# Update dependencies
nix flake update

Next steps

For template users

If you’re using this as a template for your project:

1. Customize the template - Follow Template usage guide to rename packages and update configuration
2. Set up CI/CD - Follow CI/CD setup guide for GitHub Actions automation
3. Configure secrets - Follow Secrets management guide for SOPS setup
4. Write tests - Follow Testing guide to add your own tests
5. Deploy - Deploy to Cloudflare Workers or your preferred platform

For contributors

If you’re contributing to this template:

1. Read contributing guidelines - See CONTRIBUTING.md
2. Understand architecture - Read Architecture decisions
3. Follow conventions - Use conventional commits for semantic versioning
4. Test changes - Run full test suite before committing
5. Create atomic commits - Commit changes immediately after editing

Common tasks

Adding a new page

Create a new markdown file in packages/docs/src/content/docs/:

# Create a guide
touch packages/docs/src/content/docs/guides/my-guide.md

# Add frontmatter
cat > packages/docs/src/content/docs/guides/my-guide.md << 'EOF'
---
title: My guide
description: Description of my guide
---

Content here...
EOF

The page will be automatically available at /guides/my-guide/.

Adding a new package

To add another package to the monorepo:

# Create package directory
mkdir -p packages/my-package/src

# Create package.json
cd packages/my-package
# ... add package configuration

See Template usage guide for details.

Running commands in specific packages

# Using just (recommended)
just docs dev              # Run dev in docs package

# Using bun directly
bun run --filter '@infra/docs' dev

Deploying to Cloudflare Workers

# Build and deploy
cd packages/docs
bun run deploy

# Or use justfile
just cf-deploy-production

See CI/CD setup guide for automated deployment.

Troubleshooting

Nix issues

Problem: “experimental features not enabled”

Solution: Enable flakes in nix configuration (see Prerequisites above)

---

Problem: Direnv not activating automatically

Solution:

# Add to ~/.bashrc or ~/.zshrc
eval "$(direnv hook bash)"  # or zsh

---

Problem: “error: getting status of ‘/nix/store/…’: No such file or directory”

Solution: Rebuild the flake:

nix develop --rebuild

Bun issues

Problem: “command not found: bun”

Solution: Ensure you’re in the Nix development shell:

nix develop

---

Problem: Workspace dependencies not resolving

Solution: Reinstall dependencies:

rm -rf node_modules packages/*/node_modules
bun install

Build issues

Problem: “Module not found” during build

Solution: Check TypeScript paths and ensure all imports are correct:

just check  # Run biome check

---

Problem: Playwright browsers not found

Solution: The browsers are managed by Nix. Rebuild the development shell:

exit  # Exit current shell
nix develop --rebuild

Test issues

Problem: Tests timing out

Solution: Increase timeout in test configuration or check for hanging async operations

---

Problem: E2E tests failing with “page not found”

Solution: Ensure dev server is running or build is complete:

just build  # Build before E2E tests
just test-e2e

Getting help

Documentation

• Template usage guide - Forking and customization
• CI/CD setup guide - Automated deployment
• Testing guide - Comprehensive testing
• Secrets management guide - SOPS workflow
• Architecture decisions - Design rationale

External resources

• Nix manual - Nix package manager
• Bun documentation - Bun runtime and package manager
• Astro documentation - Astro framework
• Starlight documentation - Starlight docs framework
• Vitest documentation - Unit testing
• Playwright documentation - E2E testing

Community

• GitHub Discussions - Ask questions
• GitHub Issues - Report bugs or request features

What’s next?

Now that you’re set up, you can:

• Explore the codebase - Look at example components and tests
• Customize for your needs - Follow the template usage guide
• Build something awesome - Start creating your project

Happy coding!