Local development setup simplified

ericallam

·Apr 27, 2026·#3450chore: fix CONTRIBUTING.md setup steps and scope db:seed to webapp

The local development setup flow is faster and more reliable, dropping unnecessary build steps and fixing broken documentation paths.

Getting a fresh development environment running is often the highest hurdle for new projects. Previously, setup instructions pointed to outdated paths, and seeding the database triggered unnecessary builds across unrelated workspaces. This meant a single broken reference project could crash the whole initial pipeline.

The local development setup is now simplified. The database seeding process is scoped strictly to the webapp, bypassing fragile reference packages entirely. A working environment with a seeded local database can be spun up straight from the cloned repository without manual Postgres edits or extraneous Turborepo failures.

View Original GitHub Description

Summary

Two fixes that together get a fresh-machine setup working from CONTRIBUTING.md end-to-end with no manual workarounds:

`CONTRIBUTING.md`

Fix wrong path in the migration walkthrough: cd packages/database → cd internal-packages/database. The current path doesn't exist; this breaks step 2 for every contributor adding a migration.
Renumber duplicate 4. steps in Adding migrations and the skipped 5. in the hello-world Running section.
Combine three sequential pnpm run build --filter ... calls into one (Turbo parallelizes filters): pnpm run build --filter webapp --filter trigger.dev --filter @trigger.dev/sdk.
Add a pnpm run db:seed step after migrate. The seed creates the local user, References org, and reference projects (including hello-world with the stable proj_rrkpdguyagvsoktglnod). Removes the manual instruction to edit the externalRef column in Postgres.
Mention ClickHouse and the ClickHouse migrator alongside Postgres/Redis in the Docker step (they're already part of pnpm run docker, just invisible in the docs).
Remove the V1-era Add sample jobs section. references/job-catalog no longer exists; the hello-world flow above replaces it.

`turbo.json`

Scope db:seed to webapp#db:seed → webapp#build. The previous root-level entry queued build for every workspace package — including references-*, docs, kubernetes-provider, coordinator, etc. Only webapp actually has a db:seed script, so the rest of those builds were dead weight. Worse: a single broken reference (today, references-realtime-hooks-test failing under Turbopack with node:fs/promises) kills the whole seed pipeline.

After the change, turbo run db:seed --dry-run plan drops from 27 tasks to 20 — only webapp and its real transitive workspace deps. Reference projects no longer block seeding.

Test plan

Fresh-machine setup followed end-to-end on a wiped Postgres + ClickHouse: migrate → seed → build → webapp → CLI login → trigger dev → triggered hello-world, run completed with {"message":"Hello, world!"}.
turbo run db:seed --dry-run=json confirms 20 tasks, all webapp deps, no reference packages.
CI green on the renamed turbo task name.