Conventions & Gotchas

The accumulated conventions, testing practices, and hard-won lessons for building on the Valcraven template.

This section is the template's institutional memory. It captures the conventions the codebase already follows, the way testing is set up, the subtle differences between your local dev database and production, and a curated list of the traps that cost real debugging time to find. Reading it before you make changes will save you from re-discovering the same problems.

Everything here is grounded in the actual code and configuration you cloned. Where a lesson came from a specific incident on the template, it has been generalized so it applies to any app built on Valcraven — but the underlying mechanism is real and worth internalizing.

Code conventions — import paths, the lazy-init pattern for env-dependent services, the required API-route boilerplate, the input text-color rule, useSearchParams + Suspense, and the "things to never do" list.
Testing — what test harnesses exist (Vitest node-env unit/integration + Playwright E2E in apps/web, a Workers-pool harness in apps/realtime, and no unit harness in apps/mobile), what is and isn't covered, and the separate-test-author practice.
D1 dev/prod parity — why local SQLite and production D1 behave differently, the raw-SQL adapter, the affected-row-count gotcha, D1's restricted internal tables, and how the multi-dialect schema works.
Hard-won gotchas — the crown-jewel page: Next.js dev-server quirks, the monorepo dev-stack node_modules situation, Cloudflare Worker rename/deploy traps, Durable Object migration caveats, the lint-in-CI-vs-local quirk, the worktree symlink hazard, EMAIL_FROM, release merge lineage, and more.