Development Setup

Welcome to TimeTiles development! This guide covers contributor-specific setup and workflows.

Prerequisites

See Installation Guide for system requirements. Additionally, developers need:

Git LFS: For managing image assets in the assets package

Quick Start

Single command to get started:


# Complete initialization: setup + database + seed + start dev server
make init

The application will be available at:

Main App: http://localhost:3000
Documentation: http://localhost:3001

💡 Note: make init handles everything - dependencies, .env files, Git LFS, database setup, seeding, and starts the dev server.

Essential Commands

Development


make dev          # Start all apps with database
make dev-full     # Start infrastructure and dev server in one step
make check-ai     # Run lint and typecheck (ALWAYS run after changes)
make test-ai      # Run all tests (AI-friendly output)

Testing


make test                           # Run all tests
make test-ai                        # Run tests with AI-friendly output
cd apps/web && pnpm test:debug      # Debug tests with logs
cd apps/web && pnpm test:e2e        # End-to-end tests

Database


cd apps/web && pnpm payload:migrate:create  # Create new migration
cd apps/web && pnpm payload:migrate         # Run migrations
make db-reset                               # Reset database

Database Seeding

Populate your database with test data. You can use either the Makefile command (from project root) or the pnpm command (from apps/web):


# From project root (recommended)
make seed ARGS="development"                # Seed with development preset
make seed ARGS="testing --truncate"         # Seed with testing preset, clear first
 
# From apps/web directory
pnpm seed [preset] [collections...] [options]

Presets (controls data characteristics):

minimal - Bare minimum for production
testing - Fast, deterministic data for tests (default in CI)
e2e - Moderate data for E2E testing
development - Rich, realistic data (default)
demo - Polished data for demos
benchmark - Large volumes for performance testing

Key Options:

--truncate - Clear existing data before seeding
--volume <level> - Control data volume (minimal|small|medium|large|xlarge)
--random - Use random seed for different data each run
--seed <number> - Use specific seed for deterministic randomness

Examples:


# Using Makefile (from project root)
make seed ARGS="development"                # Seed with development preset
make seed ARGS="testing --truncate"         # Seed testing data, clear first
make seed ARGS="users events"               # Seed only specific collections
 
# Using pnpm (from apps/web)
pnpm seed                                   # Seed with development preset
pnpm seed testing                           # Seed with testing preset
pnpm seed users events                      # Seed only specific collections
pnpm seed --truncate                        # Clear data and re-seed
pnpm seed help                              # Show all options

Development Workflow

Making Changes

Create a feature branch: git checkout -b feature/your-feature
Make your changes following the existing code patterns
ALWAYS run: make check-ai (runs lint and typecheck)
Write tests for new functionality
Update documentation if needed

Code Standards

Use pino logger, never console.log
Follow existing import patterns and path aliases
Handle errors explicitly with proper logging
Use React Query for server state management
Follow TypeScript best practices

Commit Guidelines

We use Conventional Commits for consistent commit messages:


feat(web): add new timeline component
fix(api): resolve import validation error
docs(readme): update installation instructions

Architecture Overview

TimeTiles uses a modern, performant tech stack:

Frontend: Next.js 15 with Turbopack, React 19
CMS: Payload CMS 3 for content management
Database: PostgreSQL 17 + PostGIS 3.5 for geospatial data
State Management: React Query + Zustand + nuqs
Styling: Tailwind CSS with shadcn/ui components

For detailed architecture information, see the Architecture Documentation.

Testing Strategy

We maintain three levels of testing:

Unit Tests: Fast, isolated component and utility tests
Integration Tests: API endpoint tests with test database
E2E Tests: Full user workflow tests with Playwright

See Testing Guidelines for detailed information.

Common Issues & Solutions

Port Already in Use


lsof -ti:3000 | xargs kill -9

Database Connection Issues


make down && make up

Clean Reset


make clean && make up

Next Steps

Architecture Deep Dive: Architecture & Tech Stack
API Development: REST API
Deployment: Deployment Guides
Contributing: Check the project README for contribution guidelines

Need Help?

Issues: Report bugs on GitHub Issues
Discussions: Join community discussions
Code Review: All PRs require review before merging