tsconfig

name: tsconfig description: 'TypeScript config conventions for this monorepo: the two-base layering, the eight leaf tiers, and the never-redeclare list. Use when adding a package, editing any tsconfig.json, picking a tier for a new app, or debugging module resolution.' metadata: author: epicenter version: '1.0'

tsconfig conventions

Every package here is source-only .ts: exports point at ./src/*.ts, there is no build step, and consumers (Bun, Vite, WXT, Tauri, the Cloudflare Worker) operate on raw .ts. That single fact decides the whole config.

The one rule

A leaf tsconfig.json may set only: types, library-only strictness (noUnusedLocals/noUnusedParameters), checkJs (SvelteKit), and genuinely package-specific options (jsx, paths, customConditions, include).

Anything else belongs in a base. If a leaf option repeats a base value or a TypeScript default, delete it.

Two base files

tsconfig.base.json   universal: target/lib[ESNext], module preserve, strict,
                     noEmit, isolatedModules, verbatimModuleSyntax, types []
tsconfig.dom.json    extends base; its ONLY job is lib [ESNext, DOM, DOM.Iterable]

There is no tsconfig.base.lib.json and no project references. Source-only packages never emit, so composite/declaration/outDir have no place here.

Module strategy: one, repo-wide

module: "preserve" + moduleResolution: "bundler". preserve implies bundler (TS 5.4+); the explicit pair is kept for legibility. Never use NodeNext anywhere: nothing in this repo is published as emitted Node ESM, and bundler resolution already reads package.json imports/exports.

The eight leaf tiers

Pick the tier, copy the shape, change nothing else.

A generated config (./.svelte-kit/tsconfig.json, ./.wxt/tsconfig.json) goes last in the array so its lib/module win where they must. Never hand-edit a generated config.

The two canonical library shapes in full:

// bun library: packages/workspace, filesystem, util, sync, cli, ...
{
    "extends": "../../tsconfig.base.json",
    "compilerOptions": {
        "types": ["bun"],
        "noUnusedLocals": true,
        "noUnusedParameters": true
    }
}

// svelte library: packages/ui, svelte-utils
{
    "extends": "../../tsconfig.dom.json",
    "compilerOptions": {
        "types": ["bun"],
        "noUnusedLocals": true,
        "noUnusedParameters": true
    }
}

Never redeclare these (base value or TS default)

Putting any of these in a leaf is dead weight. Delete on sight.

types is opt-in, on purpose

The base sets types: [] to disable auto-inclusion of every node_modules/@types package. Each leaf opts in: ["bun"] for almost everything, ["node"] for the one package that uses @types/node. Do not hoist ["bun"] to a base: a package without @types/bun installed would then fail with Cannot find type definition.

include rules

• TypeScript does not merge include across extends. A leaf include fully replaces the inherited one. For SvelteKit apps this means: do not set your own include, or you drop the generated ambient.d.ts/$types globs.
• Only set include when you must narrow scope for a real reason; comment why.

Adding a new package

1. Scaffold via the monorepo skill's boilerplate.
2. Pick a tier from the table above; copy that exact shape.
3. package.json uses exports only, no main/types. Entry point is ./src/index.ts.
4. bun install at the repo root, then bun typecheck.

Background

The full rationale, the migration that established this layout, and the baseline typecheck state are in specs/20260522T190000-modernize-monorepo-tsconfig.md.