TypeScript setup

August 7, 2026 · View on GitHub

This repo uses TypeScript project references (build mode) so the editor and CLI typechecking agree without forcing every file into a single TS "environment".

The environments

We have four distinct TypeScript environments, each with its own tsconfig. The include lists below are representative; the configs themselves are the source of truth.

Client

  • Config: packages/worker/tsconfig-client.json
  • Files: packages/worker/client/** and packages/worker/universal/**
  • Environment: browser (DOM, DOM.Iterable) + JSX (remix/ui)

Put any module the browser bundle imports under packages/worker/universal/ (#universal/*). Do not append individual worker files to the client include list.

Tools

  • Config: tsconfig-tools.json
  • Files: playwright.config.ts, wrangler-env.ts, cli.ts, tools/**, packages/shared/src/**, MCP E2E tests, and a few test-support modules (see the config's include list)
  • Environment: Node 26 (scripts, configs, tests)

Worker

  • Config: packages/worker/tsconfig-worker.json, with packages/worker/tsconfig-worker-typecheck.json as the config actually used by CLI typechecking and the root solution file (it extends tsconfig-worker and remaps #client/app-root.tsx to an SSR stub). packages/worker/tsconfig.json is a thin extends wrapper for the editor.
  • Files:
    • packages/worker/src/**/*.ts
    • packages/worker/universal/**
    • packages/worker/env.d.ts, packages/worker/src/env-schema.ts
    • generated packages/worker/worker-configuration.d.ts (via npm run generate-types)
  • Environment: Cloudflare Workers (WebWorker, WebWorker.Iterable)

Backup control plane

  • Config: packages/backup-control-plane/tsconfig.json
  • Files: packages/backup-control-plane/src/**
  • Environment: Cloudflare Workers (standalone backup Worker)

Solution config (project references)

The root tsconfig.json is the solution file:

  • It has no include.
  • It references tsconfig-tools.json, packages/worker/tsconfig-client.json, and packages/worker/tsconfig-worker-typecheck.json.

npm run typecheck runs:

  • nx run worker:typecheck — which runs tsc -b packages/worker/tsconfig-client.json packages/worker/tsconfig-worker-typecheck.json --noEmit
  • then tsc --noEmit -p packages/backup-control-plane/tsconfig.json

The root solution file (and therefore tsconfig-tools.json) is used by the editor, not by npm run typecheck.

Generated worker types (packages/worker/worker-configuration.d.ts)

packages/worker/worker-configuration.d.ts is generated and must never be edited by hand.

  • To update it, run npm run generate-types.
  • This file is allowed to include relative ./src/... imports since it is generated by Wrangler.
  • If you see this file change in a PR, it should be explainable by changes to Worker bindings/config (for example packages/worker/wrangler.jsonc) or by re-running the generation script.

Common gotchas

  • Missing editor types usually means the file isn't included by any of the environment configs. Add it to the appropriate tsconfig.*.json.
  • Client/worker shared code belongs in packages/worker/universal/, not in a one-off tsconfig-client.json include entry. See import boundaries.
  • Worker types depend on the generated packages/worker/worker-configuration.d.ts; run npm run generate-types if bindings/types drift.