A well-chosen tsconfig.json makes TypeScript predictable: it defines what code is checked, how modules are resolved, what JavaScript is emitted, and which guarantees your team can rely on. This practical checklist explains how to configure TypeScript for frontend applications, Node.js services, libraries, and larger workspaces without copying options you do not need.
Overview
tsconfig.json is both a compiler configuration file and a description of your project boundary. Before changing an option, answer three questions:
- Which files belong to this project?
- Is TypeScript checking code, emitting JavaScript, or both?
- Which runtime or build tool will execute the output?
Start with a small configuration and add options to solve a specific requirement. A typical application configuration might look like this:
{
"compilerOptions": {
"target": "ES2022",
"module": "NodeNext",
"moduleResolution": "NodeNext",
"strict": true,
"esModuleInterop": true,
"skipLibCheck": true,
"sourceMap": true,
"outDir": "dist",
"rootDir": "src",
"noEmitOnError": true
},
"include": ["src"],
"exclude": ["node_modules", "dist"]
}
This is a starting point, not a universal preset. Frontend bundlers, Node.js runtimes, test runners, and library build systems may each need different module settings. The important practice is to make the relationship between TypeScript and the rest of the toolchain explicit.
For a focused explanation of stricter checking, see the TypeScript tsconfig guide to strict compiler options. If you are debugging a configuration-related error, the practical TypeScript debugging guide can help separate compiler problems from application code problems.
Checklist by scenario
Frontend application
- Define the source boundary. Use
includefor the application source and explicitly exclude generated output. Your bundler often controls JavaScript emission, sonoEmit: truemay be appropriate when TypeScript is used only for checking. - Match the bundler's module assumptions. Do not select a module setting based only on the syntax in your source files. Confirm whether the bundler expects ES modules, CommonJS, or another format, and keep editor, test, and build configurations aligned.
- Choose a realistic target.
targetcontrols the JavaScript language level TypeScript emits. It does not polyfill missing runtime APIs, so runtime compatibility may also require your bundler or application tooling. - Keep source maps available for debugging. Enable
sourceMapwhen emitted code is inspected in a browser or debugging environment. Verify that the final build preserves the maps you expect. - Check framework-specific files. JSX, generated route types, and framework declarations may require additional includes or a framework-provided configuration. Avoid replacing those settings without understanding what they support.
When working on components, configuration is only part of the type-safety picture. The guide to React TypeScript patterns for props, events, hooks, and forms covers the application-level conventions that sit on top of the compiler.
Node.js application or service
- Align module settings with the runtime. Decide whether the service is treated as an ES module or CommonJS project, then configure
moduleand related package metadata consistently. A mismatch can produce imports that compile but fail when executed. - Use a clear output directory. Set
rootDirto the source boundary andoutDirto a directory such asdist. Keep generated files out of the input set so a second compilation does not read its own output. - Emit declarations only when needed. An internal service usually does not need
declarationfiles. A package consumed by other TypeScript projects generally does. - Use source maps deliberately. If production or staging errors are mapped back to TypeScript, ensure the runtime, debugger, and deployment process handle source maps consistently.
- Separate checking from execution. TypeScript verifies types; it is not automatically the process manager, test runner, or runtime loader. Make those responsibilities visible in package scripts.
Reusable library or package
- Set a public API boundary. Use
declaration: truewhen consumers need type declarations, and review which entry points are exposed rather than publishing every internal module. - Consider declaration maps.
declarationMapcan help consumers navigate from declarations to source when the package is published with the required source files. - Choose an output strategy before choosing options. A package may need one or more module formats, but producing multiple formats from one configuration can make paths and declarations difficult to reason about. Separate configurations or a dedicated build tool may be clearer.
- Do not hide API errors. Keep
noEmitOnErrorenabled for release builds so an invalid public type surface does not become a published artifact. - Test the package as a consumer. A successful local build does not prove that exports, declaration paths, and module resolution work after publishing.
Monorepo or multi-project workspace
- Give each project one responsibility. Separate application, library, test, and tooling configurations when their inputs or outputs differ.
- Use project references for explicit dependencies. Referenced projects can establish build boundaries and support incremental workflows. Read the project references guide before introducing them into a workspace.
- Share only stable defaults. A base configuration can hold strictness and common language settings, while each package owns its module, output, and file-boundary decisions.
- Keep generated files out of references. Confirm that output directories, temporary declarations, and coverage files are not accidentally included in multiple projects.
What to double-check
strict and its family of checks: Treat strict: true as the preferred baseline for new projects. It enables a group of related checks, including important nullability and function-safety rules. Existing JavaScript migrations may need a staged approach: enable strictness for new directories, fix errors by category, and avoid weakening the entire project to silence one difficult file.
include, exclude, and files: These options define the program TypeScript sees. exclude is not a universal ignore rule if an excluded file is imported by an included file. When behavior is surprising, inspect the resolved configuration and the compiler's file list rather than guessing.
module and moduleResolution: These settings answer different but related questions: what module syntax is emitted, and how imports are located. Use a pairing supported by your runtime or bundler. If an import works in the editor but fails at runtime, inspect package exports, file extensions, path rules, and the actual build output.
Path aliases: baseUrl and paths can improve import readability, but TypeScript's understanding of an alias does not automatically teach every runtime, test runner, bundler, or deployment tool how to resolve it. Configure each consumer or prefer relative imports where the operational complexity is not worth it.
Performance options: incremental can reduce repeated checking by storing build information. Use it when the build environment can safely retain and invalidate that metadata. skipLibCheck can reduce noise from declaration files, but it does not repair incompatible application types; treat it as a deliberate trade-off, not a substitute for resolving your own errors.
Common mistakes
- Copying a configuration without copying its assumptions. A config designed for a bundler may be wrong for a directly executed Node.js service or a published library.
- Changing
targetto fix missing APIs. Language syntax transformation and runtime API availability are separate concerns. Check the runtime, library declarations, and polyfill strategy. - Using aliases only in TypeScript. Imports may pass type-checking and still fail in tests or production if those tools do not share the alias configuration.
- Emitting into the source tree. Generated JavaScript beside TypeScript files can create duplicate modules, confusing imports, and accidental commits. Use a dedicated output directory.
- Turning off strictness globally for a local problem. Prefer a narrow type fix, a temporary migration boundary, or a documented per-file exception. Broad settings hide unrelated defects.
- Assuming editor behavior equals command-line behavior. Editors can discover a parent configuration or use a different project context. Run the same TypeScript command used by continuous integration when investigating discrepancies.
For compiler messages involving duplicate declarations, compare included files, installed type packages, and global declarations before adding arbitrary renames. The duplicate identifier troubleshooting guide provides a focused diagnostic path.
When to revisit
Review your tsconfig.json before a planning cycle, a runtime or bundler change, a JavaScript-to-TypeScript migration phase, or a move from a single package to a workspace. Also revisit it when build times grow, generated files appear in type errors, a package changes its public entry points, or developers report that editor and CI results differ.
Use this short review checklist:
- Run the project's normal type-check and build commands from a clean state.
- Inspect the resolved configuration and confirm the intended files are included.
- Compare module output and module resolution with the actual runtime or bundler.
- Verify that aliases, declarations, source maps, and output paths work in tests and deployment.
- Record why non-obvious options such as relaxed strictness,
skipLibCheck, or custom paths exist. - Remove obsolete workarounds after upgrading surrounding tools or completing a migration.
A maintainable TypeScript configuration is not the one with the most options. It is the one whose boundaries, guarantees, and output match how the project is actually built and run. Treat the file as shared project documentation, and future configuration changes become easier to review and safer to make.