Contributing

This guide covers how to set up your development environment and contribute to @fairgarden/docs.

Getting Started

Prerequisites

Node.js 22.18.0+
pnpm 11.9.0+ (npm install -g pnpm@11.9.0)

Setup

# Clone the repository
git clone https://github.com/fairgarden/docs.git
cd docs

# Install dependencies
pnpm install --no-frozen-lockfile

# Build all packages
pnpm release:build

# Start dev server
pnpm docs:dev

Development Commands

Command	Description
`pnpm docs:dev`	Start docs dev server
`pnpm docs:build`	Build docs site
`pnpm docs:validate`	Validate docs files
`pnpm release:build`	Build all packages
`pnpm typescript`	Type check
`pnpm eslint`	Lint code
`pnpm prettier`	Format code
`pnpm test --run`	Run all tests
`pnpm test --run {name}`	Run specific test file
`pnpm test:browser --run`	Run browser tests (requires podman/docker)
`pnpm test:browser:unconfined`	Run browser tests directly (CI/Playwright image)

Important

Always run pnpm prettier, pnpm eslint, pnpm typescript, and pnpm docs:validate before submitting a PR.

Development Workflow

1. Write tests first

Create or modify tests before changing implementation. When fixing bugs, write a failing test that reproduces the issue first:

src/{functionName}/{functionName}.test.ts      # Unit tests
src/{functionName}/user.spec.ts                # Integration tests
src/{functionName}/optimization.test.ts        # Performance tests

2. Write documentation

Document public functions in MDX:

docs/app/lib/{category}/{function-name}/page.mdx
docs/app/lib/{category}/{function-name}/demos/{demo-name}/index.ts

3. Implement the feature

Follow the Architecture patterns for consistency.

4. Validate

pnpm release:build && pnpm typescript && pnpm eslint && pnpm prettier && pnpm test --run

Project Structure

packages/docs/
├── src/
│   ├── CodeHighlighter/        # React components
│   ├── useCode/                # React hooks
│   ├── pipeline/               # Build-time processing
│   │   ├── loadPrecomputed*/   # Webpack loaders
│   │   ├── loadServer*/        # Server-side loaders
│   │   ├── syncTypes/          # Type extraction
│   │   └── transform*/         # Markdown transformers
│   ├── abstractCreate*/        # Factory utilities
│   └── cli/                    # CLI commands
└── build/                      # Built output

docs/app/lib/
├── architecture/               # System design docs
├── components/                 # Component documentation
├── hooks/                      # Hook documentation
├── functions/                  # Function documentation
├── patterns/                   # Architectural patterns
└── commands/                   # CLI documentation

Code Conventions

Naming

Functions are named {Purpose}{Object} for alphabetical sorting:

Prefix	Purpose	Example
`load`	Load data from files/network	`loadServerCodeSource`
`parse`	Parse strings into structures	`parseSource`
`transform`	Transform data structures	`transformMarkdownCode`
`sync`	Update committed files	`syncTypes`
`create`	Factory functions	`createDemo`
`abstract`	Factory factory functions	`abstractCreateDemo`
`use`	React hooks	`useCode`
`with`	Configuration plugins	`withFairGardenDocs`

React components use {Object}{Purpose}: CodeHighlighter, CodeProvider.

File Organization

src/{functionName}/
├── {functionName}.ts           # Main implementation
├── {functionName}.test.ts      # Unit tests
├── {helperFunction}.ts         # Split out large helpers
├── types.ts                    # Complex/shared types
├── errors.ts                   # Custom error classes
├── constants.ts                # Large string constants
└── index.ts                    # Re-exports

Code Style

ESM only - No CommonJS
Named exports - Avoid default exports
Type-safe - Minimize any, prefer unknown with narrowing
async/await - Avoid .then() chains
Parallelize - Use Promise.all() for independent async operations

Testing Guidelines

Unit Tests

Test each helper function independently
Use generic placeholder data (e.g., Button, Checkbox)
Avoid mocks when possible
Use inline snapshots for long string outputs

describe('parseSource', () => {
  it('highlights TypeScript code', () => {
    const result = parseSource('const x = 1', 'example.ts');
    expect(result.type).toBe('root');
  });
});

Integration Tests

Cover real user scenarios
Serve as supplemental documentation
Changes indicate breaking changes

// user.spec.ts
describe('user can highlight code', () => {
  it('renders highlighted TypeScript', async () => {
    // Test the full pipeline
  });
});

Adding a New Feature

New Function

Create src/{functionName}/{functionName}.ts
Add tests at src/{functionName}/{functionName}.test.ts
Export from src/{functionName}/index.ts
Add to package.json exports
Document at docs/app/lib/functions/{function-name}/page.mdx

New Component

Create src/{ComponentName}/{ComponentName}.tsx
Keep TSX minimal - extract logic to .ts files
Mark client components with 'use client'
Document at docs/app/lib/components/{component-name}/page.mdx

New webpack Loader

Create src/pipeline/loadPrecomputed{Name}/loadPrecomputed{Name}.ts
Add to withFairGardenDocs default patterns if appropriate
Document configuration options

File Conventions

This extends Next.js filesystem conventions with special handling for documentation files.

./app/**/demos/*/index.ts - Load Precomputed Code Highlighter
./app/**/demos/*/client.ts - Load Precomputed Code Highlighter Client
./app/**/types.ts - Load Precomputed Types
./app/sitemap/index.ts - Load Precomputed Sitemap

Workspace Commands

When working with workspace packages, use the -F flag:

# Add a dependency
pnpm -F @fairgarden/docs add lodash

# Remove a dependency
pnpm -F @fairgarden/docs remove lodash

# Always dedupe after adding dependencies
pnpm dedupe

Warning

Do not manually edit package.json to add/remove dependencies. Use pnpm commands to keep ordering deterministic.

Versioning

The package uses 0.x.0 versioning to allow breaking changes while working toward a stable 1.0.0. Breaking changes should improve developer experience and be documented in the changelog.

Getting Help

Read the Architecture to understand system design
Check existing tests for usage examples
Review similar implementations in the codebase