Local Development Setup
Relevant source files
The following files were used as context for generating this wiki page:
Kocteau is designed with a local-first philosophy for contributors. The development environment relies on a Docker-backed local Supabase stack and a Next.js web application. This setup ensures that developers can work on core features like authentication, music reviews, and discovery algorithms without requiring production credentials or access to live services.
The environment utilizes pnpm as the package manager and turbo for monorepo task orchestration. The primary development surface is located in apps/web, which interacts with local Supabase services including Postgres, Auth, and Storage.
Sources: README.md:104-106, CONTRIBUTING.md:4-22, AGENTS.md:55-66
Core Prerequisites and Stack
Before starting, ensure the local system has Docker installed (required for the Supabase CLI) and pnpm version 9.15.3 or higher.
| Component | Technology | Description |
|---|---|---|
| Package Manager | pnpm | Manages dependencies and monorepo workspaces. |
| Framework | Next.js (App Router) | Powers the web application in apps/web. |
| Database | Postgres (via Supabase) | Local database running on port 54322. |
| Auth | Supabase Auth | Handles OTP-first authentication locally. |
| Email Testing | Inbucket | Captures local OTP emails on port 54324. |
| Styling | Tailwind CSS + shadcn/ui | UI component and styling framework. |
Sources: package.json:11-16, README.md:88-102, supabase/config.toml:39-117
Installation and Environment Configuration
The setup process involves installing dependencies, starting the local infrastructure, and configuring environment variables.
Initial Setup Commands
pnpm install
pnpm supabase:start
pnpm supabase:status
cp apps/web/.env.example apps/web/.env.local
pnpm supabase:reset
pnpm supabase:types
pnpm dev:web
Sources: CONTRIBUTING.md:23-31, README.md:108-116
Environment Variables
Local development requires specific variables in apps/web/.env.local. These values are obtained by running pnpm supabase:status.
| Variable | Local Default / Source | Description |
|---|---|---|
NEXT_PUBLIC_SITE_URL | http://localhost:3000 | The local web application URL. |
NEXT_PUBLIC_SUPABASE_URL | http://127.0.0.1:54321 | The local Supabase API gateway. |
NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY | (From supabase:status) | The local anon key for browser-side Auth. |
Sources: README.md:120-130, CONTRIBUTING.md:35-39
Infrastructure and Data Flow
Kocteau's local environment uses a Docker-based architecture to simulate the full Supabase cloud stack. This includes the database, authentication server, and an email testing server.
Local Services Architecture
This diagram represents the relationship between the local Next.js frontend and the Dockerized Supabase services.
Sources: supabase/config.toml:10-120, README.md:118-120
Authentication and Email Testing
Kocteau uses an OTP-first (One-Time Password) flow. In local development, actual emails are not sent. Instead, they are captured by the Inbucket service.
- Login/Signup: The user enters an email at
/login. - OTP Generation: Supabase Auth generates a 6-digit code.
- Interception: The local SMTP server (Inbucket) intercepts the email.
- Verification: The developer opens the Inbucket UI at
http://127.0.0.1:54324to retrieve the code and enter it into the app.
Email Template Development
Developers can preview transactional email templates using a dedicated command:
pnpm --filter web email:dev
This starts the React Email preview server on port 3001.
Sources: README.md:118-120, apps/web/emails/README.md:7-12, apps/web/package.json:7
Development Workflow and Scripts
The project uses several scripts to manage the local database state and maintain code quality.
Database Management
| Command | Action |
|---|---|
pnpm supabase:reset | Resets the local database and re-runs migrations and seeds. |
pnpm supabase:types | Generates TypeScript definitions from the local schema. |
pnpm supabase:lint | Runs the SQL linter against local migrations. |
Sources: package.json:23-28, README.md:139-144
Pre-PR Checks
Before submitting changes, contributors are expected to run the following validation suite:
pnpm supabase:lint
pnpm --filter web lint
pnpm --filter web build
git diff --check
Sources: CONTRIBUTING.md:43-48, package.json:44
Database Seeding
When the database is reset using pnpm supabase:reset, it automatically loads deterministic data from the supabase/seeds directory. This ensures every developer starts with the same baseline of preference tags and editorial starter picks.
supabase/seeds/00_preference_tags.sql: Configures the initial set of musical taste tags.supabase/seeds/10_editorial_starter_picks.sql: Loads curated track prompts used for the cold-start experience.
Sources: supabase/config.toml:57-61, README.md:163-169
Conclusion
The local development setup for Kocteau provides a self-contained environment that mirrors production behaviors through local Supabase containers. By following the standard installation and configuration steps, developers can iterate on the core music discovery loop, test authentication flows via Inbucket, and ensure database consistency through automated migrations and seeding.