A reliable TypeScript project starts with more than a tsconfig.json. This practical template brings together compiler settings, ESLint, testing, build scripts, and GitHub Actions CI, then adapts them for React, Next.js, Node.js, and publishable packages. Use it as a starting point, and return to the checklist whenever your framework, module target, or toolchain changes.
Overview
A production-ready TypeScript project should make the safe path easy. The compiler should catch incorrect assumptions, lint rules should expose maintainability problems, tests should run consistently on every machine, and CI should verify the same commands that developers use locally.
There is no single ideal configuration for every application. A browser application, a Next.js project, a Node API, and a reusable package have different runtime and module requirements. The useful part of a TypeScript starter kit is therefore not a rigid collection of settings; it is a small, understandable baseline that can be adjusted deliberately.
The examples below assume a modern Node-based repository using npm scripts. Replace npm with your package manager of choice, and pin or update dependency versions according to the compatibility requirements of your framework and deployment environment.
Recommended project layout
my-project/
├── src/
│ ├── index.ts
│ └── __tests__/
├── dist/
├── package.json
├── tsconfig.json
├── tsconfig.build.json
├── eslint.config.js
├── vitest.config.ts
└── .github/
└── workflows/ci.yml
Keep generated output such as dist, coverage reports, and framework caches out of source control. For larger applications, separate domain code, infrastructure, and entry points rather than allowing every module to import from every other module. See the TypeScript project structure guide for a deeper approach to boundaries.
A strict baseline
Strictness is most useful when it is enabled from the beginning. A practical application configuration might look like this:
{
"compilerOptions": {
"target": "ES2022",
"module": "NodeNext",
"moduleResolution": "NodeNext",
"rootDir": "src",
"outDir": "dist",
"strict": true,
"noUncheckedIndexedAccess": true,
"exactOptionalPropertyTypes": true,
"noImplicitOverride": true,
"noFallthroughCasesInSwitch": true,
"forceConsistentCasingInFileNames": true,
"esModuleInterop": true,
"skipLibCheck": true,
"sourceMap": true,
"declaration": false
},
"include": ["src"]
}
Do not copy module and moduleResolution blindly into a framework-managed project. React build tools may expect a bundler-oriented configuration, while Next.js supplies much of its own compiler setup. The important best practice is to make the runtime and module format explicit, then verify the emitted code or framework build rather than relying on intuition. The tsconfig reference explains the trade-offs behind these options.
Checklist by scenario
For a React application
- Use the compiler and JSX settings required by the selected bundler or framework.
- Type component props, event handlers, and custom hooks at their public boundaries.
- Keep browser-only APIs out of modules that may be imported by server code.
- Run type-checking separately from the development server, for example with
tsc --noEmit. - Test behavior rather than implementation details, and keep rendering tests close to the component they cover.
For practical patterns covering props, events, hooks, and component APIs, use the TypeScript with React guide.
For Next.js
- Let Next.js own framework-specific compilation and routing conventions.
- Keep server-only dependencies and secrets out of client components.
- Check the boundary between server and client components when passing props; serializable data is generally the safest contract.
- Run the framework build in CI, not only a standalone TypeScript check.
- Keep aliases consistent between
tsconfig.json, tests, and the framework configuration.
A Next.js project may need a framework-specific test environment and separate handling for server modules, route handlers, and browser components. Treat the generated configuration as part of the framework contract instead of replacing it with a generic starter.
For a Node.js API
- Choose ESM or CommonJS deliberately and keep
package.json, TypeScript, tests, and deployment aligned. - Validate external input at runtime. TypeScript types disappear when JavaScript runs, so request bodies, environment variables, and third-party responses still need validation.
- Separate transport types from domain types where an API must remain stable while internal code changes.
- Test error paths, authorization boundaries, and malformed input rather than only successful responses.
- Build before starting production code, and run the compiled output in a clean environment.
For runtime schemas and API data, see the TypeScript runtime validation guide. Static API typing and runtime validation solve different problems and are strongest when used together.
For a reusable package
- Emit declarations and verify that consumers can import the package through the documented entry points.
- Test the package from a consumer-like environment, not only through direct source imports.
- Define the supported module formats and export map before publishing.
- Check that source maps, declaration files, and package files do not expose unintended implementation details.
- Run a packed-install test before releasing.
Package authors should follow a release checklist covering declarations, ESM, CommonJS, and exports in this TypeScript package publishing guide.
Scripts worth standardizing
{
"scripts": {
"dev": "tsx watch src/index.ts",
"build": "tsc -p tsconfig.build.json",
"typecheck": "tsc --noEmit",
"lint": "eslint .",
"lint:fix": "eslint . --fix",
"test": "vitest run",
"test:watch": "vitest",
"test:coverage": "vitest run --coverage",
"check": "npm run typecheck && npm run lint && npm test",
"ci": "npm run check && npm run build"
}
}
Use a separate build configuration when tests, stories, or scripts should be type-checked but not emitted:
{
"extends": "./tsconfig.json",
"compilerOptions": {
"noEmit": false,
"declaration": true
},
"exclude": ["**/*.test.ts", "**/*.spec.ts", "**/__tests__/**"]
}
ESLint and testing setup
For a flat ESLint configuration, keep the baseline small and add framework rules only when the framework needs them:
import eslint from '@eslint/js';
import tseslint from 'typescript-eslint';
export default tseslint.config(
eslint.configs.recommended,
...tseslint.configs.recommended,
{
ignores: ['dist', 'coverage', '.next'],
rules: {
'@typescript-eslint/no-explicit-any': 'warn',
'@typescript-eslint/consistent-type-imports': 'error'
}
}
);
Adjust the rules to the repository rather than suppressing errors globally. A focused TypeScript ESLint setup is easier to maintain than a long list of exceptions.
For Vitest, a minimal configuration can be:
import { defineConfig } from 'vitest/config';
export default defineConfig({
test: {
environment: 'node',
coverage: { reporter: ['text', 'html'] }
}
});
Use a browser-like environment for DOM-focused React tests. Jest can fill the same role, but its transform, module, and environment settings must match the project. Do not assume that a test runner will understand TypeScript path aliases or ESM without explicit configuration.
What to double-check
Build tools have different responsibilities. Choose based on the artifact you need, not on a generic claim that one tool is always faster or better.
| Tool or approach | Good fit | Check before adopting |
|---|---|---|
tsc | Type-checking and straightforward library or Node builds | Whether it emits the module format and asset types your runtime needs |
| esbuild | Fast bundling or transpilation with a small configuration | That type-checking still runs separately; transpilation alone is not type-checking |
| SWC | Fast JavaScript and JSX transformation, often through a framework | How decorators, paths, source maps, and test transforms are handled |
| Framework build | React and Next.js applications with routing, assets, or server boundaries | Which settings the framework owns and which commands CI must run |
Before merging a configuration change, verify five boundaries:
- Source boundary: Are only intended files included in type-checking and builds?
- Runtime boundary: Does emitted code match the Node or browser runtime that executes it?
- Module boundary: Do imports, exports, aliases, and package metadata agree?
- Data boundary: Are external values validated instead of trusted because a TypeScript type was declared?
- Quality boundary: Do local and CI commands run the same lint, test, type-check, and build steps?
For test strategy, mocks, coverage, and reliable workflows, use the TypeScript testing guide.
Common mistakes
- Using
anyto finish the migration: Prefer an explicit unknown value, a narrower type, or a validation schema. If an exception is necessary, keep it local and explain it. - Confusing transpilation with type-checking: SWC and esbuild can transform TypeScript without proving that the program is type-safe. Keep
tsc --noEmitor an equivalent checker in CI. - Mixing module systems accidentally: A project can appear to work in a development tool while failing after compilation. Test the actual build output.
- Ignoring generated configuration: Frameworks may rewrite or extend TypeScript settings. Review configuration changes instead of repeatedly overwriting them.
- Testing only happy paths: Add cases for invalid input, missing environment variables, rejected promises, and permission failures.
- Making CI different from local development: Put the canonical commands in
package.json, then call those commands from CI.
When a compiler diagnostic is unclear, consult the TypeScript error troubleshooting reference rather than weakening the configuration immediately.
When to revisit
Review this template before a new project, before a seasonal planning cycle, and whenever a workflow or tool changes. A TypeScript upgrade, Node runtime change, ESLint configuration migration, framework upgrade, or switch from CommonJS to ESM can affect more than one file.
Use this upgrade checklist:
- Read the release notes for TypeScript, the framework, test runner, linter, and build tool you are changing.
- Update the local runtime and CI runner together where compatibility requires it.
- Run type-checking with the new compiler before changing application code.
- Review module resolution, JSX, path aliases, declaration output, and source maps.
- Run lint, unit tests, coverage if used, and the production build from a clean install.
- For packages, test imports from the packed artifact and inspect the generated declarations.
- Record intentional rule suppressions and configuration exceptions in the repository.
The final practical action is to save the commands that passed: npm run check and npm run build. If those commands are reproducible locally and in GitHub Actions, your starter configuration is doing its job.
name: CI
on:
push:
pull_request:
jobs:
verify:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: 20
cache: npm
- run: npm ci
- run: npm run ci
Keep the runner version, package-manager lockfile, and project engines aligned. Recheck this workflow when your supported Node versions or dependency setup changes; a CI file is part of the project template, not an afterthought.