Satūs

A modern Next.js 16 starter with React 19, Tailwind CSS v4, and optional WebGL. Satūs means "beginning" in Latin.

Note: This README is for template developers. For client handoff, see PROD-README.md.

Requirements

Quick Start

bun install
bun run setup:project    # Interactive setup - choose integrations
cp .env.example .env.local
bun dev

Or skip setup and keep everything: bun install && bun dev

Tech Stack

Project Structure

app/                    # Next.js pages and routes
components/             # UI components
lib/                    # Everything non-UI
  ├── hooks/           # Custom React hooks
  ├── integrations/    # Third-party services
  ├── styles/          # CSS & Tailwind
  ├── webgl/           # 3D graphics (optional)
  └── dev/             # Debug tools (optional)

Mental model: UI → components/, everything else → lib/

Documentation

Scripts

bun dev              # Development server
bun build            # Production build
bun lint             # Biome linter
bun run generate     # Generate pages/components
bun run setup:project  # Configure integrations
bun run handoff      # Prepare for client delivery

Client Handoff

Prepare the codebase for client delivery:

bun run handoff

This interactive script: - Removes example pages and Satūs branding - Swaps README with production version - Generates component inventory - Updates package.json with project name

Key Conventions

• Images: Use @/components/ui/image (never next/image directly)
• Links: Use @/components/ui/link (auto-handles external links)
• CSS Modules: Import as s → import s from './component.module.css'
• Debug Tools: Toggle with Cmd/Ctrl + O

Deployment

vercel

Required GitHub Secret: VERCEL_TOKEN for Lighthouse CI workflow.

See ARCHITECTURE.md for deployment checklist and cache strategies.

License

MIT — Built by darkroom.engineering