Setting Up a TypeScript Project: tsconfig.json, Strict Mode & Build Tools

A single tsc hello.ts command is enough to learn the language, but it’s not how any real project runs TypeScript. Real projects have a tsconfig.json controlling dozens of compiler behaviors, a decision about which tool actually runs the code, and — critically — an opinion on strict mode that determines how much of TypeScript’s safety you’re actually getting.

This guide sets up a project the way you’d actually maintain one: a tsconfig.json you understand line by line, and a clear picture of when to reach for tsc, ts-node, tsx, or a bundler.

Starting a Project

mkdir my-ts-project && cd my-ts-project
npm init -y
npm install --save-dev typescript @types/node
npx tsc --init

@types/node deserves a mention on its own: it’s not TypeScript itself, it’s a package of type declarations for Node.js’s built-in modules (fs, path, http). Without it, import fs from 'fs' type-checks fs as any — TypeScript doesn’t ship knowledge of Node’s APIs, so a separate @types/* package (from the community-maintained DefinitelyTyped project) supplies it. This pattern — @types/<package-name> — is how thousands of untyped JavaScript libraries get TypeScript support without their maintainers writing a line of TypeScript.

npx tsc --init generates a tsconfig.json with every option listed and commented out, which is useful for browsing but overwhelming as a starting point. Here’s a trimmed, realistic one:

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "NodeNext",
    "moduleResolution": "NodeNext",
    "outDir": "./dist",
    "rootDir": "./src",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true,
    "declaration": true,
    "sourceMap": true
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules", "dist"]
}

The Options That Actually Matter

target — which JavaScript version comes out the other end

"target": "ES2022"

target controls what syntax tsc is allowed to emit. Write an async function with target: "ES5" and the compiler rewrites it into verbose generator-based polyfill code so it runs on ancient engines; write the same function with target: "ES2022" and it passes through nearly unchanged, because modern engines (and modern Node.js) already support async/await natively. Targeting a version newer than your actual deployment environment supports is a real, silent-until-runtime failure mode — if you ship target: "ES2022" output to a runtime that predates it, features like top-level await simply don’t exist there.

module and moduleResolution — how imports get resolved

"module": "NodeNext",
"moduleResolution": "NodeNext"

This pair tells TypeScript to follow Node.js’s actual module resolution algorithm (respecting package.json’s "type": "module" field, .mjs/.cjs extensions, and export maps) rather than an older, looser algorithm. Get this mismatched with your actual runtime’s module system and you’ll see the confusing “Cannot use import statement outside a module” error at runtime — even though tsc compiled without complaint, because compilation and module resolution are checked somewhat independently.

strict — the single flag that changes everything

"strict": true

strict: true is shorthand for enabling a bundle of separate checks simultaneously — most importantly strictNullChecks, noImplicitAny, and strictFunctionTypes. Without it, TypeScript’s type checking is dramatically weaker than most tutorials assume:

// strict: false (or unset — false is the historical default)
function getUser(id: number) {
  if (id === 0) return null;
  return { id, name: "Alice" };
}

const user = getUser(1);
console.log(user.name);   // No error! TypeScript doesn't know user could be null here

// strict: true
function getUser(id: number) {
  if (id === 0) return null;
  return { id, name: "Alice" };
}

const user = getUser(1);
console.log(user.name);   // Error: 'user' is possibly 'null'

This single difference — strictNullChecks — is arguably the most valuable thing TypeScript does, and it’s off unless strict is explicitly enabled. A huge share of “TypeScript didn’t catch this obvious bug” complaints trace back to a tsconfig.json that never turned strict mode on. New projects should enable strict: true from day one; the cost of retrofitting it onto a large codebase later (fixing every now-flagged nullable access) is real and grows with the codebase’s size.

noImplicitAny — refusing to silently give up

// noImplicitAny: false
function process(data) {     // data is implicitly 'any' — no error, but also no type safety at all
  return data.whatever.deeply.nested;
}

// noImplicitAny: true (included in strict: true)
function process(data) {     // Error: Parameter 'data' implicitly has an 'any' type
  return data.whatever.deeply.nested;
}

any is TypeScript’s escape hatch — a value typed any gets zero checking, silently, for every operation performed on it. noImplicitAny doesn’t ban any outright; it bans TypeScript from silently defaulting to it when it can’t infer a type, forcing you to write data: any explicitly if you really mean it. That explicitness is the whole point — an accidental any from a missing annotation is invisible until it causes a runtime crash somewhere far from where the mistake was made.

skipLibCheck — a pragmatic performance trade-off

"skipLibCheck": true

Without this, tsc type-checks every .d.ts declaration file pulled in from node_modules — including ones from unrelated packages, some of which have genuinely broken or conflicting type definitions. skipLibCheck: true skips checking library type files and only checks your own source, which is both faster and avoids being blocked by a bug in someone else’s published types. The trade-off: it also means you won’t be warned if two of your dependencies ship genuinely incompatible type declarations for the same global — rare in practice, and the default recommendation almost everywhere for this reason.

esModuleInterop — smoothing over CommonJS/ES module friction

// esModuleInterop: false
import * as express from 'express';

// esModuleInterop: true — matches what most developers actually expect
import express from 'express';

Node’s module ecosystem has spent years straddling CommonJS (require/module.exports) and ES modules (import/export). esModuleInterop makes TypeScript’s handling of default imports from CommonJS packages behave the way developers coming from Babel or plain JavaScript already expect — without it, importing a CommonJS default export forces the more awkward import * as x syntax above.

tsconfig Options at a Glance

Running TypeScript: Four Real Options

tsc (compile, then run separately) — the ground-truth approach. Slower iteration loop (edit → compile → run), but it’s exactly what production deployments do: compile once during the build, ship plain JavaScript, never touch tsc again at runtime.

tsx — the modern successor to ts-node. Uses esbuild under the hood to transpile TypeScript to JavaScript in memory, without type-checking, and runs it immediately. Fast enough for a tight development loop (tsx watch src/index.ts), but because it skips type-checking entirely, it will happily run code with type errors in it — pair it with a separate tsc --noEmit step in CI to actually catch those.

ts-node — the older tool doing the same job, optionally with full type-checking enabled (slower, but catches errors tsx won’t by default). Largely superseded by tsx for day-to-day development, but still common in existing projects and documentation.

Bundlers (Vite, webpack, esbuild, swc) — for frontend applications, these tools transpile TypeScript as part of building your JS bundle, almost always via esbuild or swc rather than tsc itself, because both are dramatically faster at transpilation (they skip full type-checking, trading it for speed). This is why a Vite dev server can hot-reload a TypeScript file in milliseconds — it isn’t running the TypeScript compiler’s type checker at all, just stripping types syntactically.

Type-Checking as a Separate CI Step

Because fast tools (tsx, esbuild, swc) skip type-checking to stay fast, a production pipeline typically adds it back as an explicit gate:

{
  "scripts": {
    "dev": "tsx watch src/index.ts",
    "build": "tsc",
    "typecheck": "tsc --noEmit"
  }
}

npm run typecheck   # runs the full type checker, emits nothing, just reports errors — exit code 1 on failure

tsc --noEmit is the command CI pipelines run to fail a build on type errors without needing the compiled output at all — a lightweight, purpose-built check separate from the actual build step, and one of the most common package.json scripts you’ll find in any serious TypeScript repository.

A Minimal Project Structure That Scales

my-ts-project/
├── src/
│   ├── index.ts
│   └── utils/
│       └── format.ts
├── dist/              ← generated by tsc, gitignored
├── tsconfig.json
├── package.json
└── .gitignore          ← must include "dist" and "node_modules"

// package.json scripts, a realistic starting point
{
  "scripts": {
    "dev": "tsx watch src/index.ts",
    "build": "tsc",
    "start": "node dist/index.js",
    "typecheck": "tsc --noEmit"
  }
}

Keeping src and dist separate (via rootDir/outDir) rather than compiling files in place is worth the small extra config — it makes .gitignore-ing generated output trivial, and it means nobody accidentally hand-edits a compiled .js file thinking it’s the source.

Common Setup Mistakes

Frequently Asked Questions

Do I need tsconfig.json for a tiny script? Not strictly — tsc hello.ts works standalone. But the moment you have more than one file, or care about module resolution, strict mode, or output location, a config file removes ambiguity that would otherwise need repeating as command-line flags every time.

Should I commit dist/ to git? No, for application code — it’s generated, reproducible output, and committing it just creates merge conflicts and staleness risk. Libraries published to npm are the exception: consumers need the compiled dist/ folder (and ideally .d.ts files), so it’s typically built as a release step, not committed to the main branch history.

What’s the difference between tsc --noEmit and just running tsc? tsc alone type-checks and writes compiled .js files to outDir. --noEmit runs the identical type-checking pass but writes nothing — purely a validation step, which is why it’s the natural choice for a CI gate that shouldn’t produce build artifacts.

Can I gradually add TypeScript to an existing JavaScript project? Yes — this is one of TypeScript’s core design goals. Start with allowJs: true and checkJs: false in tsconfig.json, rename files to .ts one at a time, and turn on strict only once most of the codebase is converted. Trying to enable strict: true on day one of a large migration usually produces an overwhelming wall of errors that stalls the whole effort.

What’s Next

With a real tsconfig.json and a build pipeline in place, you’re set up the way production TypeScript projects actually work — not just running single files through tsc. Next: Basic Types in TypeScript, where we cover the type vocabulary — primitives, arrays, tuples, and the crucial difference between any, unknown, and never — that everything else in this series builds on.