Development Setup

Environment setup and day-to-day development workflows for TimeTiles.

Quick Start

git clone https://github.com/jfilter/timetiles.git
cd timetiles
make init    # installs deps, starts DB, runs migrations, seeds, starts dev server

• App: localhost:3000 
• Dashboard: localhost:3000/dashboard 
• Docs: localhost:3001  (run pnpm dev in apps/docs)

See Quick Start for prerequisites and database mode options.

Commands

make format and pnpm format run only the formatter, without lint autofixes. Prefer named files to avoid unrelated formatting changes. make check-ai reports whole-tree formatting failures even when other checks are scoped.

make clean deletes the development database; make fresh does the same and then migrates and reseeds it. Back up any data you need before using either command. Docker cleanup is limited to this project’s Compose resources; it does not prune other projects’ resources.

make check-ai without arguments runs Oxlint and TypeScript checks across the packages, including Shared and the scraper SDK. FILES="..." lints only the requested files and filters TypeScript diagnostics to them. Package selectors are web, docs, ui, and timescrape; the legacy scraper alias selects the TimeScrape runner, not the SDK.

All packages lint with the root .oxlintrc.json. ESLint plugins without a native Oxlint port (SonarJS, security, JSDoc, boundaries and others) run inside Oxlint as JS plugins; the local wrappers in scripts/oxlint/ supply configuration that plain JSON cannot express, such as absolute paths for the boundaries resolver.

Database Seeding

make seed ARGS="development"            # Rich, realistic data (default)
make seed ARGS="testing --truncate"     # Fast, deterministic data for tests
make demo-berlin                        # Site setup plus all data packages, imported immediately

Available presets: testing, e2e, development, deploy (the idempotent site bootstrap deployments run). Add --truncate to clear existing data first. For demo content, make demo-data installs the data packages and make setup-site creates the site pages and navigation.

Workflow

1. Create a feature branch from main
2. Make your changes
3. Run make check — lint and typecheck must pass
4. Write tests for new functionality
5. Commit using conventional commits
6. Open a pull request

Code Standards

• TypeScript strict mode — all code must pass strict type checking
• Named imports only — import { foo } from 'bar'
• No console.log — use logger.info() / logError() from @/lib/logger
• React Query for all data fetching — never fetch directly in components
• Coordinates in [longitude, latitude] order (GeoJSON standard)
• PostGIS for spatial queries — no client-side geo computations

Layered Architecture

The lib/ directory follows a strict import hierarchy:

Layer 0 — Foundation
  utils/, security/, types/, constants/, geospatial/, filters/, definitions/, schemas/

Layer 1 — Infrastructure (can import Layer 0)
  services/, database/, middleware/

Layer 2 — Domain (can import Layer 0 + 1)
  ingest/, account/, export/, email/, collections/, blocks/

Layer 3 — Application
  api/, hooks/, jobs/, config/, context/, globals/, openapi/, seed/, data-packages/, metadata/

Each layer can only import from the same layer or below. scripts/oxlint/boundaries.mjs enforces this and declares per-file exceptions, including foundation configuration helpers and the Payload composition root.

Migrations

make migrate-create    # Auto-generate from schema changes
make migrate           # Apply pending migrations

Never create migration files manually — always use Payload’s generator.

Troubleshooting

Further Reading

• Commit Guidelines — Conventional commit format and scope rules
• Testing Guidelines — Test types, mocking rules, and patterns
• Documentation Guide — JSDoc and MDX conventions
• Payload Deadlocks — Prevention patterns for CMS hooks