OpenParable
Skip to content
← Back to skills

Tsconfig

Development
tsconfig

Tsconfig is an Agent Skill for development published in the EpicenterHQ/epicenter repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

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.

View on GitHub ↗
QUICK START

How to use this skill

Bring this guide into your coding agent with a prompt tailored to the tool you use.

  1. Open your project in Codex.
  2. Copy and paste the prompt below.
  3. Review files and risks before approving any action.
Prompt to paste
Inspect the Agent Skill at https://github.com/EpicenterHQ/epicenter/blob/HEAD/.agents/skills/tsconfig/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/tsconfig, but wait for my approval before writing files or running scripts.

Copying this prompt does not install or run the skill. Review third-party files before use.

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.

TierextendsLeaf adds
Bun library"../../tsconfig.base.json"types:["bun"], noUnusedLocals, noUnusedParameters
Node library"../../tsconfig.base.json"types:["node"], noUnusedLocals, noUnusedParameters
Svelte library"../../tsconfig.dom.json"types:["bun"], noUnusedLocals, noUnusedParameters
SvelteKit app["../../tsconfig.base.json", "./.svelte-kit/tsconfig.json"]checkJs:true, types:["bun"]
Cloudflare Worker"../../tsconfig.base.json"jsx, jsxImportSource, types, include
Bun app"../../tsconfig.base.json"types:["bun"], include
Astro app["../../tsconfig.base.json", "astro/tsconfigs/strict"]astro include/exclude
WXT extension["../../tsconfig.dom.json", "./.wxt/tsconfig.json"]customConditions, paths, include

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.

Do not write in a leafWhy
module: "preserve"already in tsconfig.base.json
moduleResolution, target, noEmit, strict, isolatedModulesalready in the base
lib: ["ESNext"]the base default; use tsconfig.dom.json if you need DOM
noPropertyAccessFromIndexSignature: falsethat is already the TS default
useDefineForClassFields: truedefault when target >= ES2022
forceConsistentCasingInFileNamesdefault true since TS 5.0
resolvePackageJsonExportsdefault true under moduleResolution: bundler
sourceMapno-op under noEmit
single-element extends arrayuse the string form: "extends": "../../tsconfig.base.json"

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.