multiworker-gotchas

name	multiworker-gotchas
description	Fork and template gotchas (env import, routes, typegen, forms, D1, Turbo, HMR, new DO packages). Use when working on apps/web or durable-objects, or when behavior diverges from this stack’s conventions.

Cloudflare multi-worker — fork / template gotchas

These trip up new contributors and agents most often. For commands and checklists, see multiworker-workflow.

1. Worker bindings and env — Import the typed env from the Workers virtual module, not from React Router context: import { env } from "cloudflare:workers". Do not use context.cloudflare.env (or similar) for Cloudflare bindings in this stack. More: workers-patterns.mdc.

1b. Imports — no cross-package re-exports — Import each symbol from the module that defines it. @internal/auth-client = session/client/binding code; @internal/auth-db/api-schemas = wire types and Zod schemas; @internal/auth-db/constants = shared auth constants. Do not re-export auth-db (or any other package) from auth-client’s index.ts for convenience. Full rule: typescript-imports.mdc.

2. Generated artifacts

   • Never hand-author files meant to be generated.
   • Drizzle: edit packages/db/src/schema.ts or durable-objects/<name>/src/schema.ts; set drizzle.config.ts driver (d1-http vs durable-sqlite); run bun run db:generate or the package’s db:generate.
   • Generated-only: drizzle/*.sql, drizzle/meta/*.json, driver migration wrappers, React Router +types, lockfiles, .alchemy/. PRs should flag hand-written Drizzle output unless explicitly intentional.

3. Route path export — Each file under apps/web/app/routes/ should export its path for @firtoz/router-toolkit (forms, typed submitters), matching app/routes.ts (export const route: RoutePath<"/login"> = "/login";). routing/SKILL.md.

4. Regenerate types and verify often

   • After routes, alchemy.run.ts, or env changes: bun run typegen (repo root), then bun run typecheck and bun run lint during the task—not only before a PR.
   • Bindings or alchemy.run.ts changed: bun run typegen then bun run typecheck from the repo root. multiworker-workflow.
   • ALCHEMY_PASSWORD and CHATROOM_INTERNAL_SECRET have no in-repo defaults. bun run setup / setup:local → variable browser (TTY). bun run setup -- --yes or CI=true → auto-fill only regeneratable secrets into .env.local. setup:staging / setup:prod → stage dotfiles (copy from .env.local offered in the browser).

5. Loaders and actions return Promise<MaybeError<...>>

   • Import success / fail / MaybeError from @firtoz/maybe-error (not from @firtoz/router-toolkit).
   • Loaders: annotate return type; narrow with loaderData.success. Actions: prefer formAction. form-submissions, routing.

6. Index route + formAction / useDynamicSubmitter → 405

   • In-app: use formAction, useDynamicSubmitter, await submitter.submitJson(...), and exported route paths.
   • Outside the router (curl, plain HTML, tools): POSTs to an index route must use /?index; POST / alone will not hit the index action.
   • Prefer a non-index resource route for public create/join APIs.

7. Export formSchema (and related router-toolkit exports) for typed submitters when you use them. form-submissions/SKILL.md.

8. Alchemy + D1

   • packages/db/alchemy.run.ts (ALCHEMY_APP_IDS.database, package @internal/db) defines D1Database with migrationsDir → packages/db/drizzle.
   • apps/web/alchemy.run.ts imports mainDb from @internal/db/alchemy.
   • Alchemy applies SQL on deploy/dev per D1 + Drizzle.
   • Do not hand-manage D1_DATABASE_ID for the default flow; do not add runtime CREATE TABLE fallbacks in loaders/actions—fix schema / migrations / local state instead.

9. Turbo / stale typegen — If route types look wrong, run bun run typegen -- --force. turborepo/SKILL.md.

10. JSDoc — Do not use */ inside a /** ... */ block (it ends the comment early). General TypeScript gotcha.

11. Empty or stale local D1

12. bun run db:generate after schema changes.

13. bun run dev (repo root) so @internal/db + web apply packages/db/drizzle.

14. Still no such table? Confirm migration output, D1Database.migrationsDir still packages/db/drizzle, restart dev; only then consider resetting local Alchemy/D1 state (documented troubleshooting—not routine).

15. Biome check --write — Can modify files after you think you are done; re-run bun run lint or review the diff before finishing.

16. Dev server port

• Vite may use 5174+ if 5173 is busy—don’t assume a fixed port when testing in a browser.
• Do not pin server.hmr.port: client + SSR each run an HMR WebSocket server.
• @cloudflare/vite-plugin ignores Vite HMR (sec-websocket-protocol: vite…) and forwards other /api/ws/* upgrades to Miniflare.

14. Prod D1 / visitors errors — If /visitors fails after deploy, confirm bun run deploy:prod (or bun run --cwd packages/db deploy:prod with the same STAGE) completed and D1 migrations ran; see Alchemy D1Database.

15. New Durable Object / worker package

• Typing: import type { CloudflareEnv } and new Hono<{ Bindings: CloudflareEnv }>() so c.env is typed.
• RPC types: workers/rpc.ts (no import from ../env there). Add package.json#exports "./workers/rpc" when consumers need it.
• WorkerRef / cross-worker: one direction uses workspace:*; the other uses a relative ../<pkg>/workers/rpc import to avoid Turbo cycles.
• New Alchemy app: root package.json dev filter.
• Destroy graph: turbo.json <pkg>#destroy:* with dependsOn → matching @internal/web#destroy:*.
• Wire web: apps/web workspace dep; apps/web/alchemy.run.ts binding; apps/web/workers/app.ts forwarder if WebSockets. Typed HTTP over the binding: binding-hono-client (bindingHonoClient, BindingClientApp map).
• DO SQLite: src/schema.ts, drizzle.config.ts with driver: "durable-sqlite", package db:generate; never hand-edit generated migrations.
• Do not add another package’s workers/app.ts to tsconfig.cloudflare.json include—it can break web Env.
• Step-by-step: durable-object-package, web-alchemy-bindings, worker-rpc-turbo, binding-hono-client (service-binding HTTP).

16. WebSocket forwarding

• Handle Worker upgrade paths before React Router.
• Keep client URL prefix and worker route prefix the same (e.g. /api/my-feature/ws/).
• Don’t break Vite HMR WebSockets; forward the DO subpath to /websocket on the DO.
• Socka RPC + push: socka-realtime + @firtoz/socka (chatroom-do, packages/chat-contract). Avoid hand-rolled JSON wire protocols unless the user wants raw WS.

17. SSR / browser boundary — Routes run on the server first.

• Never in module scope, loaders/actions, render, or SSR useMemo: window, document, WebSocket, canvas, localStorage, other DOM APIs.
• OK: useEffect, handlers, ClientOnly, guarded client-only code.
• WebSocket URL helpers may use window.location only when called from client-only code—or pass origin in.
• No localhost / 127.0.0.1 / placeholder WS URLs as runtime defaults.

18. Durable Object RPC using in local dev

• Real DO responses may be using-compatible; Vite SSR / some Miniflare paths return plain Response.
• If using res = await api.get(…) throws Symbol.dispose errors → use const res = … or guard disposers.
• using api = honoDoFetcherWithName(…) is usually safer (library guards missing stubs).

19. Alchemy dev stale web process state

• Symptom: log shows webUrl for 5173 but the port is dead after a crash.
• Delete .alchemy/pids/ entry for the web workspace package (slug from apps/web/package.json name, e.g. @internal-web or scoped form depending on Alchemy) and the matching .alchemy/web/local/ JSON.
• Ensure the web package log file under .alchemy/logs/ exists (empty file is fine), then bun run dev. Never commit .alchemy/.

20. CLOUDFLARE_API_TOKEN vs CLOUDFLARE_ACCOUNT_ID

• Must be one Cloudflare account—swapped or mismatched values → [CloudflareStateStore] 404 text/html, wrong workers.dev subdomain, confusing deploy failures.
• Align dashboard Account ID, token Account Resources, and .env.staging / .env.production.
• On GitHub: CLOUDFLARE_ACCOUNT_ID = Environment variable (workflows use vars); token = Secret.
• More: workers-env-local.

21. Optional PostHog / analytics

• POSTHOG_* — optional like WEB_*; empty → no analytics.
• Remove completely: drop posthogRequirements from apps/web/env.requirements.ts; delete unused apps/web/app/** helpers (component, analytics*.ts); remove extra alchemy.run.ts bindings; bun remove @posthog/* / posthog-js from apps/web if present.
• Root README: Optional: PostHog.

22. Preview deploy vs destroy — top-level requireEnv

• alchemy destroy loads alchemy.run.ts the same way alchemy deploy does: any requireEnv("…") at module scope must be set for destroy:preview too.
• Locally that usually means .env.staging loaded via alchemy-cli --stage staging|preview (same as deploy:preview / destroy:preview). In CI, mirror Turbo deploy (preview) env: on Destroy PR preview in .github/workflows/pr-deploy.yml — otherwise post-merge teardown fails with … is not set from a worker/DO alchemy.run.ts (e.g. APP_PUBLIC_BASE_URL).
• Alternatives: avoid module-scope requireEnv for vars only needed at runtime, or use a destroy-safe placeholder where appropriate.

23. trustedDependencies replaces Bun’s default script allowlist

• In Bun’s installer, if the root lockfile has an explicit trusted set (from package.json trustedDependencies), only those package names may run install lifecycle scripts. The built‑in default list is used only when trustedDependencies is omitted (hasTrustedDependency in lockfile.zig).
• This repo lists esbuild, msgpackr-extract, sharp, and workerd — the native/downloader-style packages that have needed install hooks here. After adding a dependency that legitimately requires scripts, add its published name (or run bun pm trust <name> / bun add --trust once) and re-run install.
• [install] ignoreScripts = true in bunfig.toml blocks all lifecycle scripts, including names in trustedDependencies — do not combine it with this allowlist approach.
• [install] optional = false is still incompatible at the repo level (Vite / Rolldown, workerd, Tailwind oxide, sharp platform packs).

24. Minimum release age (bunfig.toml)

• [install] minimumReleaseAge = 172800 (2 days in seconds) limits installs to npm versions published at least that long ago. Docs. Use minimumReleaseAgeExcludes for packages that must track bleeding-edge. Mostly affects new resolution, not rewriting an existing bun.lock.

25. New env secret “synced” but Worker binding missing

• Turbo strips env vars not listed in root turbo.json → globalEnv before alchemy deploy. GitHub Environment sync + job env: showing MY_KEY: *** is not enough if Turbo never forwards the key.
• Also map MY_KEY: ${{ secrets.MY_KEY }} in pr-deploy / main-push / prod-deploy (sync ≠ workflow map). Mirror module-scope requireEnv keys on preview destroy jobs too.
• Checklist + CI guard: workers-env-local § Checklist after changing env or bindings, bun run check:ci-env-wiring, always-apply rule new-env-var-checklist.mdc.

Also load

• workers-patterns.mdc — short always-on reminder for workers, env, routes.
• new-env-var-checklist.mdc — full checklist when adding secrets/vars.
• realtime-websockets.mdc — Socka default, no fake WebSocket hosts (when working on durable-objects/*, apps/web, or /api/ws).
• socka-realtime/SKILL.md — end-to-end Socka + DO + web checklist.