tsconfig
Configure a tsconfig.json by runtime — pick module, moduleResolution, target, strict, and emit for a bundler, Node, library, or browser-ESM project, and fix the module/strict/emit errors a wrong config causes. Use when setting up or editing a tsconfig.json, choosing module or moduleResolution, adding project references for a monorepo, or resolving TypeScript module-resolution / verbatimModuleSyntax / declaration / strict errors. Not for bundler config files (vite.config, webpack.config) themselves — only the TypeScript compiler options.
- License 许可
- MIT
- 最近更新
- 2026-11-15
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- name
- tsconfig
- metadata
- { "category": "reference" }
- description
- Configure a tsconfig.json by runtime — pick module, moduleResolution, target, strict, and emit for a bundler, Node, library, or browser-ESM project, and fix the module/strict/emit errors a wrong config causes. Use when setting up or editing a tsconfig.json, choosing module or moduleResolution, adding project references for a monorepo, or resolving TypeScript module-resolution / verbatimModuleSyntax / declaration / strict errors. Not for bundler config files (vite.config, webpack.config) themselves — only the TypeScript compiler options.
02 资源文件 1
- 参考文档OPTIONS.md7.8 KB
03 SKILL.md 正文
tsconfig by runtime
A tsconfig.json is runtime-driven: module, moduleResolution, target, strict, and emit follow where the output runs, not preference. One tsconfig represents one environment — server code, DOM code, worker code, tests each get their own, connected with project references. Run this guide once per tsconfig.
How to use
- Identify the runtime the output of this tsconfig runs in (bundler / Node / library / browser-ESM).
- Apply the matching row of the decision table, then every library rule or project-reference rule that applies.
- Set each of
module,moduleResolution,target,strict,emitwith a one-line reason; drop anything an implied value already provides.
Done when all five are set with a stated reason and no implied value is set redundantly.
Principle
- Resolution is infectious or portable.
moduleResolution: "bundler"is infectious — it permits extensionless imports that only a bundler can resolve, so the emitted code breaks in Node.moduleResolution: "nodenext"is portable — code that resolves in Node almost always resolves in bundlers too. Default to portable unless a bundler owns emit. - Libraries compile under the strictest settings. A consumer's config is unknowable; satisfying the strictest satisfies all. See library rules.
targetdownlevels, and implieslib. It decides which JS features are rewritten vs left intact, and the default ambient type definitions. Pick the lowest environment you must support.moduledrives resolution and interop, not just emit. Even withnoEmit, TS type-checks against the module format it would emit — somoduleshapes the types you see on imports.
Runtime decision table
| Runtime | module |
moduleResolution |
target |
strict |
emit |
|---|---|---|---|---|---|
| Bundler (app) | esnext (or preserve) |
bundler |
esnext, or your bundler's target |
true |
noEmit: true (or emitDeclarationOnly) |
| Node (compile + run) | nodenext |
implied nodenext |
implied esnext |
true |
default; verbatimModuleSyntax: true |
| Library | node18 (lowest Node supported) |
implied node18 |
es2020 (lowest ES supported) |
true |
declaration, declarationMap, sourceMap, rootDir, outDir, verbatimModuleSyntax |
| Browser-ESM (no bundler) | nodenext |
implied nodenext |
esnext or browser baseline |
true |
default, or noEmit if another tool emits |
Why each row:
- Bundler. The bundler resolves and emits; TS only type-checks, so
noEmitandbundlerresolution (extensionless imports, packageexports/imports). SetverbatimModuleSyntax: true(orisolatedModules) so single-file transpilers in the pipeline stay safe. Avoid"type": "module"and.mtshere — some bundlers' ESM/CJS interop can't be modeled underbundlerresolution (TS issue #54102). Usepreserveinstead ofesnextonly if a file genuinely mixesimportandrequire. - Node.
nodenextpicks CJS vs ESM per file from the extension and the nearestpackage.json"type", and enforces Node's resolution rules (extensions required on ESM relative imports). For ESM output, set"type": "module"or use.mts. Pin a specific Node version byextends-ing@tsconfig/nodeNNinstead of relying on the floatingesnexttarget. - Library. Portable by default:
node18resolution +.jsextensions in relative imports work in Node and bundlers.target/moduleset to the lowest you support so emitted code and.d.tsglobals don't assume newer runtimes. See library rules for the full strictness/emit set. - Browser-ESM, no bundler. No dedicated option;
nodenextESM rules approximate browser ESM (they enforce extensions). Usepathsto stand in for import maps — pointhttps://esm.sh/pkgat local@types, or map"*"to an empty file to reject unlisted bare specifiers.
Implied values (don't set redundantly)
Setting these explicitly is noise and can drift from the option that drives them:
module: "nodenext"⇒moduleResolution: "nodenext",esModuleInterop: true,target: "esnext"module: "node20"⇒target: "es2023"module: "preserve"⇒moduleResolution: "bundler",esModuleInterop: truecomposite: true⇒declaration: true,incremental: true,rootDir= the tsconfig directoryverbatimModuleSyntax: true⇒isolatedModules: trueesModuleInterop: true⇒allowSyntheticDefaultImports: truetarget≥ES2022⇒useDefineForClassFields: true
Library-specific rules
Libraries are different: the consumer's config is unknown, so compile under the strictest settings — satisfying them tends to satisfy all others.
strict: true, especiallystrictNullChecks. Type-level constructs land in emitted.d.tsand only error under strict.interface Sub extends Super { foo: string | undefined }is an error only withstrictNullChecks; a consumer with strict on will hit it. Code rarely errors only when strict is off, so strict is safe to impose.- Portable imports: write
.jsextensions.export * from "./utils.js"works in Node and bundlers;export * from "./utils"only works in bundlers (infectious).module: "node18"enforces this. module: "node18", notbundler. Bundler resolution is infectious — it lets through code that crashes in Node withERR_MODULE_NOT_FOUND ... Did you mean to import ./utils.js?.verbatimModuleSyntax: true. Guarantees portability regardless of the consumer'sesModuleInterop(imports that work only with or only without it are rejected), and blocksexport defaultin modules emitted as CommonJS, which would force Node-ESM and bundler consumers to consume the module differently.declaration: trueemits the.d.tsconsumers need for types.declarationMap+sourceMapadd Go-To-Definition and debugging back to your.tssource — only useful if you ship the source; both trade library size for DX, your call.rootDir+outDirseparate (e.g.src→dist). Necessary if you publish source: without it, extension substitution makes consumers load your.tsinstead of.d.ts, causing type errors and slowdowns.- Prefer not to bundle. If you do bundle, your bundler must bundle declarations too — otherwise
.d.tsfiles keep extensionless imports that error under anodenextconsumer and infect referenced types withany. If your bundler can't bundle declarations, usemoduleResolution: "nodenext"so the declarations stay consumer-safe. - Dual-emit (CJS + ESM from one compile) is not provably type-safe. A single compilation checks one output; dependencies can expose different APIs to CJS vs ESM. If you dual-emit, test both bundles (
@arethetypeswrong/cli) before publishing.
Project references for monorepos
Split a large or multi-environment program into smaller projects, each with its own tsconfig, connected with references. Gains: faster incremental builds, enforced layering, per-environment options.
references— top-level array:{ "references": [{ "path": "../src" }] }. Importing from a referenced project loads its output.d.ts, not its source.composite: trueon every referenced project — its implications are in the implied-values table; beyond those, it requires every implementation file to be matched byincludeor listed infiles(tsc names anything missed).- Build with
tsc -b(build mode). It builds referenced projects in dependency order, does up-to-date checks, and effectively forcesnoEmitOnErrorfor all projects (otherwise a stale dependency would hide its error after one build). Flags:--verbose,--dry,--clean,--force,--watch. declarationMap: trueso editors' Go-To-Definition and rename cross project boundaries.- Solution tsconfig at the root:
"files": []plusreferencesto every leaf project.tsc -bthen builds the whole graph from one entry point. (Emptyfilesis allowed once you have ≥1 reference.) extendsa shared base tsconfig to centralize commoncompilerOptions; each leaf overrides only what differs.files/include/excludeare overwritten, not merged, by the inheriting config.
Flags behind the table
strict: trueturns on the strict family (strictNullChecks,noImplicitAny,noImplicitThis,strictFunctionTypes,strictBindCallApply,strictPropertyInitialization,strictBuiltinIteratorReturn,useUnknownInCatchVariables,alwaysStrict). Default istruein modern TS. Full per-flag detail inOPTIONS.md.verbatimModuleSyntax: true— what you write is what's emitted: it errors rather than rewritingimport↔require, forcing intentional CJS vs ESM. Incompatible with dual-emit from one source. Erasure mechanics and deprecated-flag lineage inOPTIONS.md.isolatedModules: true— flags constructs single-file transpilers (Babel, swc,ts.transpileModule) can't handle; implied byverbatimModuleSyntax. Detail inOPTIONS.md.esModuleInterop: true— fixes CJS/AMD/UMD default-import interop; implied bynodenext/preserve, impliesallowSyntheticDefaultImports(type-checking only). Helper mechanics inOPTIONS.md.
For the full strict-family list, interop-flag mechanics, deprecated flags, and jsx/lib/emit knobs, see OPTIONS.md.
Symptom → fix
| Symptom | Fix |
|---|---|
ERR_MODULE_NOT_FOUND ... Did you mean to import ./utils.js? |
Relative ESM import lacks an extension. Add .js. Required under nodenext; portable for libraries. |
Cannot find module './settings.json' |
Enable resolveJsonModule. |
Default import of a CJS module errors (import x from "cjs-mod") |
Enable esModuleInterop (implied by nodenext/preserve); or use import * as x. |
verbatimModuleSyntax: import/export not rewritten to require, errors instead |
Use import x = require(...) / export = ... for CJS; set package.json "type" to match intent. |
Namespaces are not allowed in global script files when 'isolatedModules' is enabled |
Add export {} to the file, or set moduleDetection: "force". |
This syntax is not allowed when 'erasableSyntaxOnly' is enabled (param properties, enum, namespace, import =, export =, <T>x) |
You target Node's native type-stripping. Rewrite the construct, or drop erasableSyntaxOnly and use a real transpiler. |
Re-exporting a type errors under isolatedModules / a single-file transpiler |
Mark it: export { type Foo } / import type { Foo }. |
Cannot find module '...' on a side-effect import (import "./x.css") after enabling noUncheckedSideEffectImports |
Add declare module "*.css" {} in a global .d.ts. |
Consumer gets any / declaration errors from a bundled library under nodenext |
Your bundler kept extensionless imports in .d.ts. Don't bundle the library, or bundle declarations too; else set moduleResolution: "nodenext". |
verbatimModuleSyntax can't be enabled with dual CJS+ESM emit |
Fundamentally incompatible with one compile emitting both. Emit one format per compile, or drop it. |
allowImportingTsExtensions can only be used with noEmit/emitDeclarationOnly |
Set one of those — the bundler emits the JS. |
Library consumer errors under their strict but not yours |
Compile the library with strict: true; type-level code leaks into .d.ts and only errors under strict (e.g. strictNullChecks). |
exactOptionalPropertyTypes: Type 'undefined' is not assignable |
Don't assign undefined to an optional prop; add undefined to its type, or omit the key. |
04 同仓库更多 Skills
unslop
Use when writing or editing prose a person will read, or when text sounds AI-generated.
show-me
Use when asked to show, diagram, or walk through how code fits together or what a change does, or before explaining a multi-file flow in prose.
pr
Use when writing or updating a pull request description, or before running `gh pr create`.
commit
Use when writing a commit message, or before running `git commit`.
write-specs
Spec a feature's observable behavior. Use when asked for requirements, when a request says what the system should do but not how, or to capture what a built system already guarantees. Not for how to build it (write-plan).
write-skills
Write, fix, or audit a skill's frontmatter, trigger description, and body. Use when a skill is asked for, never fires, or fires at the wrong moment. Not for a hook (write-hooks) or the plugin manifest and catalog.