Build and Test

Core commands for building the site, running tests, and checking code quality.

When to Use

• •After creating or editing content, templates, or components
• •Running or writing tests
• •Checking TypeScript types or linting
• •Debugging build or test failures

Commands

Build Pipeline

1. •Scan — find all .md files in content/
2. •Parse — extract YAML frontmatter, compile Markdown
3. •Render — apply templates and resolve {{tag}} placeholders
4. •Output — write HTML to dist/
5. •Assets — copy static/ files to dist/

bun run build

Running Tests

# All tests once
bun run test:run

# Specific file
bun run test:run -- src/core/frontmatter.test.ts

# Pattern match
bun run test:run -- -t "should parse"

# With coverage
bun run test:run -- --coverage

Tests are co-located with source files:

src/core/
├── frontmatter.ts
├── frontmatter.test.ts
├── markdown.ts
└── markdown.test.ts

Writing Tests

Use Bun test with the happy-dom environment:

import { describe, it, expect } from 'bun:test';
import { MyClass } from './my-class.js';

describe('MyClass', () => {
  it('should do something specific', () => {
    const result = new MyClass().process('input');
    expect(result).toBe('expected');
  });

  it('should handle errors', () => {
    expect(() => new MyClass().process('')).toThrow('Error message');
  });
});

Rules:

• •Co-locate tests: <name>.test.ts next to <name>.ts
• •Write tests first — failing test, then implement
• •Use .js extension in imports (TypeScript path mapping)
• •Descriptive test names that read like documentation

Pre-commit Checklist

bun run typecheck && bun run lint && bun run test:run

All must pass before committing.

Troubleshooting

Tests fail:

• •Check imports use .js extension
• •Run single file to isolate: bun run test:run -- src/core/specific.test.ts
• •Focus with .only: describe.only(...) or it.only(...)

Build fails:

• •Run bun run typecheck to find type errors
• •Check frontmatter syntax in content files
• •Verify content/ directory exists

EADDRINUSE error:

• •Server is already running — don't kill it, just inform the user

See references/debugging.md for advanced debugging techniques.

References

• •references/debugging.md — Test and build debugging, CI pipeline config