TypeScript tsconfig Guide: Essential Compiler Options for Apps, Libraries, and Node.js

Overview

A TypeScript configuration should describe the boundaries and runtime assumptions of one project. It is not a list of every available compiler option. Start with the smallest configuration that accurately represents your application, then add an option when it solves a specific problem.

For most new projects, strict checking is the best foundation. A typical baseline looks like this:

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "NodeNext",
    "moduleResolution": "NodeNext",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true,
    "noEmit": true
  },
  "include": ["src"]
}

This is not universal. Browser applications often use a framework-provided configuration and a bundler-oriented module setting. Node.js projects need to align TypeScript with the package's module format. Libraries usually need declaration files and a separate build configuration. The important principle is alignment: the TypeScript compiler, runtime, bundler, test runner, and linter should not each assume a different project structure.

Options such as target, module, and moduleResolution are related but not interchangeable. target controls the JavaScript language level emitted by TypeScript. module describes the module format used for output or interpretation. moduleResolution controls how imports are located. Choose them according to the runtime or build tool that will consume the result, not according to a favorite preset.

Checklist by scenario

Frontend applications

• Begin with the framework’s generated configuration. Next.js, React tooling, and other frameworks may add JSX, path, and plugin settings that should not be replaced casually. See the Next.js and TypeScript App Router guide for framework-specific patterns.
• Set JSX through the framework when possible. A setting such as jsx affects how JSX is transformed, while the framework or bundler may own the final transformation.
• Use noEmit when a bundler owns output. TypeScript can type-check the source while a separate tool produces JavaScript, CSS, and assets.
• Keep include focused. Include application source, relevant configuration files, and tests only when they use the same configuration. Avoid compiling generated output, dependency folders, and framework caches.
• Define aliases in one place. If you use baseUrl and paths, configure the bundler, test runner, editor, and runtime to understand the same aliases. TypeScript path aliases alone do not rewrite imports in emitted JavaScript.

For forms and data-heavy UI code, compiler strictness is especially valuable because it exposes nullable values and mismatched field shapes early. A type-safe forms setup can then build on that foundation rather than compensating for loose project settings.

Node.js services

• Choose the module system deliberately. Match module and moduleResolution to whether the package uses CommonJS, native ECMAScript modules, or a build tool that defines its own conventions.
• Declare the runtime libraries. Use lib and installed type packages to describe available APIs. Do not add browser libraries to a server project merely to silence an error; that can hide accidental use of browser globals.
• Separate development checking from production output. A service may use noEmit during editor and test checks, then use a build-specific configuration to emit JavaScript and declarations.
• Check import behavior after compilation. A successful TypeScript check does not guarantee that Node.js will load every import correctly. Test the actual build and start command.
• Type external input at the boundary. Request bodies, environment variables, files, and database responses should be validated or narrowed before they enter trusted application code. Compiler options cannot validate runtime data.

If a Node.js project reports confusing import or package-entry errors, compare its configuration with the package’s module metadata and build output. The module resolution troubleshooting guide provides a useful diagnostic path.

Published libraries

• Use a source configuration and a build configuration. The source project can use noEmit for checks, while the build configuration enables declaration, declarationMap, and the required output directories.
• Keep public types intentional. declaration exposes the library’s inferred public API. Review exported types rather than assuming generated declarations are a complete API design.
• Set rootDir and outDir carefully. These options make the source-to-output relationship predictable, but they can fail when files outside the expected source tree are included.
• Test the package as a consumer. Verify that the published package’s exports, declarations, and JavaScript files agree. A library can compile successfully while consumers receive an incorrect entry point.
• Consider composite when using project references. Composite projects impose structure that enables incremental, separately buildable units. Read the project references guide before introducing them to a small package.

Monorepos and shared packages

• Give each package a clear project boundary. Avoid one root configuration that accidentally compiles every package, test fixture, and generated directory together.
• Use a shared base configuration for stable defaults. Extend it with package-specific settings for browser, server, library, and test environments.
• Use project references for buildable dependencies. References can make dependency order explicit and reduce repeated work, but every referenced project must satisfy the requirements of referenced builds.
• Keep output directories separate from source directories. This prevents generated declarations and JavaScript from becoming inputs to another package’s compilation.
• Confirm package-manager and editor behavior. Workspace symlinks, package exports, and editor project selection can expose configuration problems that a root-level check misses.

What to double-check

Strictness: strict enables a group of related checks, including safer handling of null and undefined. If enabling it in an existing JavaScript-to-TypeScript migration creates too many errors, raise the setting deliberately and track the remaining categories. Avoid permanently weakening the entire project to accommodate one difficult file.

File selection: Inspect include, exclude, and files together. Excluding a directory does not always remove an imported file from the program; imported dependencies may still be included. Use the compiler’s project inspection output when you are unsure why a file is being checked.

Declarations and source maps: Enable sourceMap for useful debugging of emitted JavaScript. Enable declaration for a library that ships types. Do not enable every output option in an application whose bundler already generates maps and artifacts.

Interop: Options such as esModuleInterop and allowSyntheticDefaultImports affect how imports are written and checked. They should match the module format and loader in use. Changing them may require updating imports, tests, or build commands.

Type packages: A broad types array can introduce globals from test or browser environments into a server project. Limit it when environment leakage causes duplicate declarations or misleading available APIs. For duplicate global errors, see how to fix duplicate identifier errors.

Tool ownership: Decide whether TypeScript owns transpilation, or whether a bundler, framework, or alternative compiler does. Then configure noEmit, source maps, decorators, JSX, and module settings around that decision. The build tools comparison can help structure this choice.

Common mistakes

• Copying a configuration without checking the runtime. A configuration that works for a browser bundle may produce unusable imports for a Node.js service.
• Using paths as a runtime alias system. It helps TypeScript resolve source imports but does not automatically change emitted paths.
• Including node_modules or build output manually. This increases noise and can create duplicate declarations.
• Mixing multiple configuration files without documenting their purpose. Name files by role, such as tsconfig.json, tsconfig.build.json, and tsconfig.test.json, and state which command uses each one.
• Fixing a type error with skipLibCheck by default. This option can reduce noise from dependency declarations, but it does not repair application types. Use it as a conscious trade-off, not as a substitute for understanding the error.
• Assuming compilation proves runtime safety. TypeScript checks static assumptions. It does not validate JSON, API responses, environment variables, or database records at runtime. The string assignment error guide is useful when narrowing and literal types need closer attention.

When to revisit

Revisit tsconfig.json before a new planning cycle, a framework or runtime migration, a build-tool change, or a monorepo reorganization. Also review it when editor diagnostics differ from CI, when test files see different globals than application files, or when a package’s emitted output cannot be consumed as expected.

Use this short review sequence:

1. Write down the project’s runtime, module format, build owner, source directory, and output directory.
2. Run the type-check and build commands from a clean state.
3. Inspect which files are included and which configuration each command loads.
4. Test a representative import, generated declaration, or bundled entry point in the real consumer environment.
5. Remove options that no longer serve the project, and document any intentional exceptions.

A configuration is healthy when a new contributor can identify what is checked, where output goes, how imports resolve, and which tool owns the final build. Keep that checklist close to the repository, and update it whenever the workflow changes.