Development Guide#

Prerequisites#

• Bun v1.3+

Setup#

bun install

Project Structure#

sitebase/
├── packages/
│   ├── core/       # Export library (@sitebase/core)
│   ├── cli/        # CLI tool (@sitebase/cli)
│   └── web/        # Web management UI (@sitebase/web)
├── scripts/        # Utility scripts
├── biome.json      # Linter/formatter config
└── tsconfig.json   # TypeScript config

Commands#

Verification#

Run these before committing:

# Run all checks (typecheck + lint)
bun run check

# Individual checks
bun run typecheck      # TypeScript type checking
bun run lint:check     # Biome lint (no auto-fix)
bun run format:check   # Biome format (no auto-fix)

Fixing Issues#

bun run lint      # Auto-fix lint issues
bun run format    # Auto-fix formatting

Code Style#

Enforced by Biome:

• Indentation: Tabs
• Quotes: Double quotes
• Imports: Auto-organized on save (via biome.json assist)

TypeScript is configured with strict mode and additional safety flags:

• noUncheckedIndexedAccess - Array/object index access may be undefined
• noFallthroughCasesInSwitch - Require break/return in switch cases
• noImplicitOverride - Require override keyword

Packages#

@sitebase/core#

Core export functionality. No runtime dependencies except Handlebars.

Key files:

• src/types.ts - Type definitions
• src/export.ts - Export logic
• src/config.ts - Config file loading
• src/templates.ts - Handlebars helpers, slugify
• src/atproto.ts - ATProto fetch utilities

@sitebase/cli#

CLI wrapper around core. Uses Commander for argument parsing.

cd packages/cli
bun run src/index.ts export --config ../path/to/config.ts

@sitebase/web#

Hono-based web server with ATProto OAuth.

cd packages/web
bun run dev

See packages/web/CLAUDE.md for web-specific details.

ATProto Integration#

The project uses ATProto lexicons:

• site.standard.publication - Blog/publication metadata
• site.standard.document - Individual documents/posts

Documents are fetched from any PDS via:

1. Parse AT URI to extract DID
2. Resolve DID to PDS endpoint via plc.directory
3. Fetch records via com.atproto.repo.getRecord / listRecords

Adding Features#

New Handlebars Helper#

Add to packages/core/src/templates.ts in registerHelpers():

hbs.registerHelper("myHelper", (arg1: unknown) => {
  // Return transformed value
  return String(arg1).toUpperCase();
});

New Export Option#

1. Add type to packages/core/src/types.ts in ExportOptions and ExportTarget
2. Handle in packages/core/src/export.ts in exportPublication()
3. Update packages/core/src/config.ts if it affects config loading
4. Document in README.md

Workspace Dependencies#

Use workspace protocol for internal deps:

{
  "dependencies": {
    "@sitebase/core": "workspace:*"
  }
}