TypeScript Project Setup: A Practical Configuration Guide for Modern Apps

Overview

TypeScript configuration lives primarily in tsconfig.json. The file tells the TypeScript compiler which files to read, which JavaScript version to produce, how modules should be resolved, how strict the type checker should be, and where generated output belongs. A good TypeScript project setup is not the one with the most options; it is the smallest configuration that matches the project’s runtime and build tool.

Start by answering four questions:

• Will a bundler such as Vite, a framework build system, or TypeScript itself produce the final JavaScript?
• Where will the code run: a browser, a server, a test runner, or more than one environment?
• Does the project need JavaScript output, declaration files, or only type checking?
• Which module system and package-manager workflow does the repository use?

These decisions should guide the configuration. Do not copy a backend configuration into a frontend application simply because both projects use TypeScript. Likewise, do not assume that an editor’s successful type checking means the production build will succeed. The compiler, bundler, test runner, and runtime each need compatible assumptions.

Before creating the project, settle on one package manager and commit its lockfile. If you are choosing between npm, pnpm, and Yarn, compare the repository workflow and team requirements rather than switching casually; the related package manager comparison provides a separate checklist.

Checklist by scenario

Frontend application with a bundler

For a Vite-style frontend or another bundler-managed application, the bundler normally handles module bundling and final asset output. TypeScript can therefore focus on type checking, while the bundler transpiles the source. A common starting point is:

{
  "compilerOptions": {
    "target": "ES2020",
    "module": "ESNext",
    "moduleResolution": "Bundler",
    "strict": true,
    "jsx": "react-jsx",
    "noEmit": true,
    "skipLibCheck": true
  },
  "include": ["src"]
}

Adjust target, jsx, and module settings to match the chosen framework and supported browsers. The important point is noEmit: true: it prevents a separate TypeScript JavaScript output directory when the bundler already owns that responsibility. Run tsc --noEmit in a dedicated type-check script, and run the normal application build separately.

Keep application source under a clear directory such as src. Exclude generated folders, dependency folders, coverage output, and build caches. If the application uses path aliases, configure them in TypeScript and in the bundler or test runner as well. An alias that exists only in tsconfig.json may type-check successfully but fail at runtime.

Node.js backend or command-line application

A backend project usually needs TypeScript to emit JavaScript into a predictable directory. A basic setup might look like this:

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "NodeNext",
    "moduleResolution": "NodeNext",
    "rootDir": "src",
    "outDir": "dist",
    "strict": true,
    "sourceMap": true,
    "declaration": false,
    "esModuleInterop": true
  },
  "include": ["src"],
  "exclude": ["node_modules", "dist", "coverage"]
}

This is a starting point, not a universal prescription. The module settings must agree with the project’s package metadata, file extensions, and runtime behavior. In particular, projects using an ESM-oriented setup may need explicit file extensions in imports or a different source layout than CommonJS projects. Test the emitted files by running the same kind of command that production will use.

rootDir defines the expected source boundary, while outDir keeps generated files away from source control. Source maps make stack traces easier to interpret during local debugging. If the service loads JSON, uses environment files, or imports assets, verify how those resources are handled after compilation; TypeScript does not automatically reproduce every non-TypeScript file in dist.

Reusable package or internal library

A library needs a stronger public API boundary than an application. Consider enabling declaration output and checking that only intended entry points are exported:

{
  "compilerOptions": {
    "target": "ES2020",
    "module": "ESNext",
    "moduleResolution": "Bundler",
    "strict": true,
    "declaration": true,
    "declarationMap": true,
    "sourceMap": true,
    "outDir": "dist",
    "rootDir": "src"
  },
  "include": ["src"]
}

Decide whether the package will publish ESM, CommonJS, or multiple formats, then configure the package metadata and build tool together. Check the generated declaration files for accidental internal types, unstable paths, and dependencies that should not be part of the public API. A library build should also test the package as a consumer would import it, rather than testing only the source files.

Shared base configuration

In a monorepo, a base configuration can standardize strictness and general quality settings while each package extends it for its own runtime. Keep environment-specific options in package-level files. For example, a browser package and a server package may need different lib, module, JSX, or output settings even when they share strict: true.

Use project references only when they solve a real boundary or build-performance problem. They add structure and can improve large repositories, but they also require consistent composite settings and build commands. Begin with separate, understandable configurations before introducing a more complex project graph.

What to double-check

1. Strictness: Enable strict: true for new projects unless there is a documented migration constraint. If an older codebase cannot adopt it immediately, turn on related checks incrementally and track the remaining exceptions.
2. Included files: Confirm that the compiler sees application code, tests where appropriate, and declaration files that matter. Remove accidental inclusion of generated output or unrelated scripts.
3. Runtime libraries: The lib setting describes available standard APIs such as DOM or newer ECMAScript features. Node projects and browser projects should not automatically use the same library assumptions.
4. Module resolution: Make sure TypeScript, the bundler, the test runner, and the runtime resolve imports in compatible ways. Many “module not found” errors are configuration mismatches rather than missing files.
5. Aliases: Test every alias in the editor, type checker, development server, test command, and production build. Configure the alias wherever resolution occurs.
6. Build boundaries: Run type checking and the production build in continuous integration. A useful script arrangement might include typecheck, test, build, and lint as separate commands.
7. Package metadata: For libraries and ESM applications, check type, exports, entry points, and generated file extensions together with module and moduleResolution.

When an error appears only in CI or production, compare the exact Node version, package-manager lockfile, environment variables, and build command. The production build debugging checklist can help separate configuration errors from dependency and deployment problems.

Common mistakes

Using one giant tsconfig for every purpose. Editor support, application builds, tests, and library declaration generation often have different needs. Use a base file and focused overrides when the environments genuinely differ.

Assuming target changes the whole application. TypeScript can transform syntax, but it does not polyfill missing runtime APIs. Browser compatibility, server runtime support, and polyfills remain build or platform decisions.

Mixing emit responsibilities. If a bundler emits application code, avoid also committing a second set of TypeScript-generated files. If TypeScript is the backend build step, ensure the deployment artifact includes the output directory and required non-code files.

Disabling strict checks to make a migration quiet. Suppressing errors can hide unsafe null handling and implicit types. Prefer a staged migration, narrow exclusions, and explicit type annotations at boundaries.

Ignoring tests in the configuration. A test runner may use a separate transform or module mode. Run tests through the same configuration assumptions as the application, and make sure test-only globals are typed without leaking them into production code.

Editing configuration without checking the lockfile. A TypeScript upgrade, framework upgrade, or package-manager change can alter resolution behavior. Review the resulting dependency tree and run a clean install before diagnosing subtle differences.

When to revisit

Revisit the TypeScript configuration before a major framework or runtime upgrade, when changing bundlers, when converting between CommonJS and ESM, or when moving code between browser and server environments. Also review it when adding a monorepo package, publishing a library, introducing a new test runner, or changing the deployment build command.

A useful maintenance routine is to inspect the configuration at the start of a planning cycle and after any toolchain change. Confirm that the package manager, TypeScript version, framework, Node or browser targets, test runner, and CI commands still agree. Then run a clean install, type check, test suite, production build, and—if the project emits files—an execution smoke test against the generated output.

Keep a short README note explaining why unusual compiler options exist. Future maintainers can then distinguish an intentional compatibility setting from an obsolete workaround. If you are unsure whether a failure is caused by malformed generated data or a build input, a focused utility such as a JSON formatter and validator can quickly rule out syntax problems in configuration files.

Final action checklist: identify the runtime, choose the build owner, enable appropriate strictness, define source and output boundaries, align module resolution across tools, verify aliases, run the production command locally, and commit the configuration with its lockfile. Repeat those checks whenever the workflow changes.