Using as a template

This guide explains how to use nix-config as a starting point for your TypeScript monorepo projects.

Quick start

Option 1: GitHub template

Click “Use this template” button on GitHub
Create your new repository
Clone to your local machine
Follow customization steps below

Option 2: Nix flake (coming soon)

nix flake init --template github:sciexp/nix-config

Option 3: Manual fork

git clone https://github.com/cameronraysmith/infra.git my-project
cd my-project
rm -rf .git
git init
git add .
git commit -m "chore: initial commit from infra template"

Understanding the naming pattern

This template uses framework-agnostic, purpose-based naming that works for both the template itself and your forked projects.

Package naming strategy

Template package: @infra/docs

Why this naming works:

Framework independence: No mention of Astro/Starlight - these are implementation details
Template perspective: Most projects need documentation - immediately useful
Brevity: Shortest meaningful name
Pattern clarity: @{scope}/{purpose} scales to multiple packages
Template duality: Works as both a working deployment and a forkable template

For your project

When you fork this template, you’ll rename packages to match your organization and project:

Single-package projects:

@myorg/docs        # If docs are your main/only package
@myorg/api         # If building an API service
@myorg/web         # If building a web application

Multi-package projects:

@mycompany/docs    # Documentation site
@mycompany/api     # API backend
@mycompany/web     # Web frontend
@mycompany/shared  # Shared utilities

Pattern: Use the package’s purpose, not its implementation framework.

Deployment subdomain patterns

Understanding how to structure your deployment URLs is important for scalability.

Subdomain hierarchy

Top-level (reserved, precious namespace)

Reserve these for organization-wide services:

example.com              # Main org site
www.example.com          # Main org site
docs.example.com         # Org-wide documentation
api.example.com          # Org-wide API gateway
blog.example.com         # Org blog

Project-level (scalable)

Use project subdomains for individual applications:

{project}.example.com                      # Project main site
{component}.{project}.example.com          # Project components

Deployment examples

Single-package projects

If your project has only one public-facing site:

Configuration:

Package: @myorg/docs
Worker: myproject
Route: myproject.example.com

When to use:

Documentation sites
Simple web applications
Single-purpose services

Multi-package projects

If your project has multiple public-facing components:

Configuration:

Package: @myorg/docs → Worker: myproject-docs → docs.myproject.example.com
Package: @myorg/api → Worker: myproject-api → api.myproject.example.com
Package: @myorg/web → Worker: myproject-web → www.myproject.example.com

When to use:

Multi-component architectures
Clear separation of concerns needed
Professional multi-service setup

Template deployment example

For infra:

Package: @infra/docs
Worker: nix-config-docs
Route: infra.cameronraysmith.net

Rationale:

Preserves docs.* for actual org documentation
ts-nix is short identifier for the template project
Shows project-level subdomain pattern

Customization checklist

When forking this template, update these files:

1. Root package.json

{
  "name": "my-project",
  "description": "Your project description",
  "repository": {
    "type": "git",
    "url": "https://github.com/yourorg/my-project.git"
  },
  "workspaces": ["packages/*"]
}

2. Package directories

Rename packages/docs/ to match your package purpose:

mv packages/docs packages/my-package-name

3. Package package.json

Update packages/my-package-name/package.json:

{
  "name": "@yourorg/my-package-name",
  "description": "Your package description",
  "repository": {
    "type": "git",
    "url": "https://github.com/yourorg/my-project.git"
  },
  "release": {
    "plugins": [
      // ... existing plugins ...
      [
        "semantic-release-major-tag",
        {
          "customTags": [
            "my-package-name-v${major}",
            "my-package-name-v${major}.${minor}"
          ]
        }
      ]
    ]
  }
}

4. Wrangler configuration

Update packages/my-package-name/wrangler.jsonc:

{
  "name": "my-project-package-name",
  "routes": [
    {
      "pattern": "my-project.example.com",
      "custom_domain": true
    }
  ]
}

5. GitHub Actions workflows

Update workflow matrices in .github/workflows/:

ci.yaml:

matrix:
  package:
    - name: my-package-name
      path: packages/my-package-name

release.yaml:

matrix:
  package:
    - name: my-package-name
      path: packages/my-package-name

6. Justfile

Update filter patterns:

# Before
bun run --filter '@infra/docs' dev

# After
bun run --filter '@yourorg/my-package-name' dev

Search and replace @infra/docs with your package name.

7. Documentation

Update:

README.md - Project name and description
CONTRIBUTING.md - Scope examples in commit message section
packages/my-package-name/README.md - Package-specific docs

8. Flake description

Update flake.nix:

{
  description = "my-project: Your project description";
  # ... rest of flake
}

Verification steps

After customization:

1. Install dependencies

nix develop
bun install

2. Build and test

# Build
just build

# Run tests
just test

# Run in development
just dev

3. Verify Nix flake

nix flake check --impure

4. Test semantic-release

# Dry run to verify configuration
just test-release

5. Update secrets

If using SOPS for secrets management:

# Generate new age keys
just sops-bootstrap dev
just sops-bootstrap ci

# Add secrets
just edit-secrets

# Upload to GitHub
just sops-upload-github-key
just sops-setup-github

See Secrets management guide for details.

Adding more packages

As your project grows, add additional packages:

1. Create package directory

mkdir -p packages/new-package/src
cd packages/new-package

2. Create package.json

{
  "name": "@yourorg/new-package",
  "version": "0.0.0-development",
  "private": true,
  "description": "Package description",
  "type": "module",
  "repository": {
    "type": "git",
    "url": "https://github.com/yourorg/my-project.git"
  },
  "license": "MIT",
  "scripts": {
    "build": "...",
    "test": "...",
    "test-release": "semantic-release --dry-run --no-ci"
  },
  "release": {
    "extends": "semantic-release-monorepo",
    "branches": [{ "name": "main" }],
    "npmPublish": false,
    "plugins": [
      // Copy from existing package
    ]
  }
}

3. Update workflow matrices

Add to .github/workflows/ci.yaml and .github/workflows/release.yaml:

matrix:
  package:
    - name: existing-package
      path: packages/existing-package
    - name: new-package
      path: packages/new-package

4. Create package-specific config

tsconfig.json extending root config
Test configuration if needed
Build configuration

5. Install and test

cd ../..
bun install
just test-pkg new-package

Removing template-specific content

After forking, you may want to remove template-specific documentation:

Optional removals

docs/notes/ - Template development notes (safe to remove)
Template-specific guides (if creating your own)
Example content in packages/docs/src/content/docs/

Keep these

CONTRIBUTING.md - Conventional commit guidelines
.github/workflows/ - CI/CD automation
justfile - Task automation (customize commands)
Nix configuration - Development environment

Enabling releases

When ready for public releases:

1. Verify conventional commits

Ensure your team understands and uses conventional commit format.

2. Test releases

# Test at root
bun run test-release

# Test per package
cd packages/my-package
bun run test-release

3. Enable workflow

Uncomment triggers in .github/workflows/release.yaml:

# Change from:
on:
  workflow_dispatch:
    inputs:
      dry-run:
        default: true

# To:
on:
  push:
    branches:
      - main
  workflow_dispatch:
    inputs:
      dry-run:
        default: false

4. Verify first release

Push a conventional commit and watch the release workflow:

git commit -m "feat(my-package): add initial functionality"
git push
gh run watch

See Architecture decisions for release strategy details.

Getting help

Template issues

If you encounter issues with the template itself:

Check GitHub Issues
Open a new issue with reproduction steps

Project-specific issues

For your forked project:

Consult the guides in this documentation
Check the Nix documentation
Review Bun workspace docs
See semantic-release docs

Next steps

After customization:

Set up CI/CD - Follow CI/CD setup guide
Configure secrets - Follow Secrets management guide
Add tests - Follow Testing guide
Deploy - Configure Cloudflare Workers or your deployment target
Start building - Create your application code

Welcome to your new TypeScript monorepo!