Lesson 4 of 4 · 12 min · TypeScript fundamentals

tsconfig.json, tooling and migrating to TypeScript

Covers: TypeScript 5.x, Vite and Node.js 22 or newer. Updated 13 Nov 2026. Part of the Frontend Developer roadmap.

What you will learn

  • What tsconfig.json does and how to create one
  • The options that matter: strict, target, module, moduleResolution, lib, jsx, noEmit, paths
  • Typical configurations for a Vite and React app, a Node.js service and a library
  • Where types come from: @types packages, .d.ts files, skipLibCheck
  • Tooling: type checking in CI, ESLint, and migrating a JavaScript project gradually

In simple words

tsconfig.json is the settings file for TypeScript. It tells the checker how strict to be, which version of JavaScript your code targets, how to find imported files and which files to include. A good configuration turns TypeScript from a gentle suggestion into a safety net, and getting it right once saves hours of confusing errors.

Words to know

  • tsconfig.json: the file that configures the TypeScript compiler and editor support.
  • Compiler option: a setting in compilerOptions, such as strict.
  • Declaration file (.d.ts): a file that describes the types of JavaScript code without containing the code.
  • Module resolution: how the compiler finds the file behind an import.

Create a configuration

npm install --save-dev typescript
npx tsc --init                     # generates tsconfig.json with comments
npx tsc --noEmit                   # type-check without writing JavaScript
npx tsc --watch --noEmit

A modern, sensible starting point for a front-end project built with Vite (and similar bundlers):

{
  "compilerOptions": {
    "target": "ES2022",
    "lib": ["ES2023", "DOM", "DOM.Iterable"],
    "module": "ESNext",
    "moduleResolution": "bundler",
    "jsx": "react-jsx",
    "strict": true,
    "noUncheckedIndexedAccess": true,
    "noFallthroughCasesInSwitch": true,
    "verbatimModuleSyntax": true,
    "isolatedModules": true,
    "skipLibCheck": true,
    "noEmit": true
  },
  "include": ["src"]
}

(Newer Vite templates split this into tsconfig.app.json and tsconfig.node.json with project references; the options are the same.) Always check the TSConfig reference for the version you use, because defaults and recommended options evolve.

The options that matter

Option What it does Recommendation
strict turns on the family of strict checks: strictNullChecks, noImplicitAny, strictFunctionTypes, strictBindCallApply, strictPropertyInitialization, useUnknownInCatchVariables, alwaysStrict always true
noUncheckedIndexedAccess array[i] and obj[key] may be undefined recommended: catches real bugs
exactOptionalPropertyTypes distinguishes a missing property from undefined optional, stricter
noImplicitOverride requires the override keyword in subclasses good for class-heavy code
noFallthroughCasesInSwitch, noImplicitReturns, noUnusedLocals, noUnusedParameters lint-like checks useful, or leave to ESLint
target the JavaScript version of the output (ES2022, ESNext) pick what your runtime supports; with a bundler it often only affects checking
lib which built-in types exist (ES2023, DOM, DOM.Iterable, WebWorker) include DOM for browser code, not for Node.js
module the module system of the output (ESNext, NodeNext, CommonJS) ESNext with a bundler, NodeNext for Node.js
moduleResolution how imports are found (bundler, NodeNext, node10) bundler for Vite and webpack, NodeNext for Node.js
jsx how JSX is compiled (react-jsx, preserve) react-jsx for React 17 and later
noEmit do not write output files true when a bundler or runtime does the transpiling and tsc is only the checker
outDir, rootDir, declaration, sourceMap output controls for libraries and Node.js builds
paths, baseUrl import aliases ("@/*": ["src/*"]) the bundler must also be told about the aliases
skipLibCheck skip type-checking .d.ts files in node_modules usually true (faster, avoids third-party conflicts)
esModuleInterop, allowSyntheticDefaultImports smoother default imports of CommonJS packages on in most setups
resolveJsonModule import .json files when needed
isolatedModules each file must be transpilable on its own required by Babel, esbuild, SWC, Vite
verbatimModuleSyntax use import type for type-only imports recommended, matches how bundlers work
erasableSyntaxOnly forbids TypeScript-only run-time syntax (enum, namespace, parameter properties) for Node.js type stripping and clean setups
allowJs, checkJs include and check JavaScript files for gradual migration

Type-only imports keep type imports from becoming run-time imports:

import type { Order } from "./types";
import { api, type ApiError } from "./api";

Node.js configuration

{
  "compilerOptions": {
    "target": "ES2023",
    "lib": ["ES2023"],
    "module": "NodeNext",
    "moduleResolution": "NodeNext",
    "strict": true,
    "noUncheckedIndexedAccess": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "outDir": "dist",
    "rootDir": "src",
    "sourceMap": true
  },
  "include": ["src"]
}

With NodeNext, relative imports need file extensions as Node.js requires (import { x } from "./x.js", even though the source is x.ts), and package.json's "type" field decides ESM or CommonJS. Install @types/node for Node.js built-in types. Run with tsx src/server.ts in development (fast, no type checking), compile with tsc for production, or use a runtime that strips types.

Libraries

Publishing a package needs declaration: true (generates .d.ts), declarationMap, a clean outDir, and the right exports and types entries in package.json. Tools such as tsup, unbuild and tsdown bundle and generate declarations. Test the package from a clean consumer project.

Where types come from

  • Your own code: inferred and annotated.
  • Libraries that ship types: most modern packages include their own .d.ts (look for "types" in their package.json).
  • DefinitelyTyped: npm install -D @types/lodash adds community-maintained types for packages without their own (@types/node, @types/react, @types/express).
  • Your own declarations for untyped modules or globals, in a .d.ts file included in the project:
declare module "legacy-lib";                       // quick: everything is any (use sparingly)

declare module "*.svg" { const url: string; export default url; }      // for bundler asset imports

// Vite environment variables:
interface ImportMetaEnv { readonly VITE_API_URL: string }
interface ImportMeta { readonly env: ImportMetaEnv }
  • Global types such as window.dataLayer: augment with declare global { interface Window { dataLayer: unknown[] } }.

Tooling

  • Editor: VS Code has TypeScript built in (hover for types, "Go to definition", rename symbol, quick fixes). Use the workspace TypeScript version (typescript.tsdk) so everyone has the same checking.
  • Type checking in CI: add a script "typecheck": "tsc --noEmit" and run it on every pull request. Bundlers such as Vite and esbuild do not type-check (they only strip types), so without this step type errors never block a build.
  • ESLint with typescript-eslint adds rules that understand types (no floating promises, no unused variables, consistent type imports, no-explicit-any). Prettier formats.
  • Testing: Vitest and Jest work with TypeScript (Vitest natively), and tsd/expectTypeOf can test types.
  • Project references ("references", tsc -b) split large repositories into separately built projects, speeding up builds.
  • Performance: keep include tight, enable skipLibCheck, use incremental, avoid enormously complex types.
  • Use npx tsc --showConfig to see the final merged configuration, and --explainFiles to learn why a file is included.

Migrating a JavaScript project

A gradual path that keeps the app working at every step:

  1. Add TypeScript and a tsconfig.json with allowJs: true, checkJs: false, noEmit: true.
  2. Make the build pipeline handle .ts and .tsx (Vite does by default).
  3. Rename files from .js to .ts (.jsx to .tsx) one at a time, starting with leaf modules (utilities, API helpers, types).
  4. Add types for the most important data: API responses, domain models, component props.
  5. Install @types/* packages.
  6. Start with strict: false (or enable strict flags one by one: noImplicitAny, then strictNullChecks), fix errors in batches, then turn on full strict.
  7. Use // @ts-expect-error (not @ts-ignore) with a comment for temporary suppressions, because it fails when the error disappears.
  8. Add the type-check step to CI, and ESLint rules to forbid new any.
  9. Validate external data with Zod at the boundaries.

JSDoc types in JavaScript files (// @ts-check with /** @param {number} n */) are another route for teams that cannot convert yet.

Common errors and fixes

Message Likely fix
Cannot find module './x' or its corresponding type declarations check path and extension, moduleResolution, install @types, add a declare module
Property 'x' does not exist on type narrow the type, fix the interface, or check lib includes DOM
Object is possibly 'undefined' handle undefined (?., ??, a guard) rather than !
Type 'X' is not assignable to type 'Y' read the nested explanation from the bottom up
Cannot use JSX unless the '--jsx' flag is provided set "jsx": "react-jsx"
'x' is declared but never used remove it, or noUnusedLocals: false
Imports work in Vite but fail in tsc align moduleResolution, paths, and the bundler aliases

The non-null assertion value! and as any silence the compiler; each one is a place where a run-time bug can hide. Keep them rare and reviewed.

Common mistakes

  • strict left off or turned off to make errors disappear.
  • Not running tsc --noEmit in CI, because the bundler does not check types.
  • Using @ts-ignore freely.
  • Mismatched module and moduleResolution.
  • Including DOM in a Node.js project (or forgetting it in a browser one).
  • Path aliases configured in tsconfig but not in the bundler.
  • Forgetting @types/node.

Try it yourself

  1. Create a project, run npx tsc --init, set the strict options above and check a few files.
  2. Add a typecheck script and make a pull request check fail on a type error.
  3. Install @types/node and @types/express and see the errors disappear.
  4. Add an import alias @/* in both tsconfig.json and the Vite config.
  5. Convert three files of a small JavaScript project to TypeScript with allowJs.

Check yourself

What does strict: true do?

It enables a family of strict type checks, including strictNullChecks and noImplicitAny, catching null and untyped-value mistakes.

Why run tsc --noEmit in CI if you use Vite?

Vite and other bundlers only remove types; they do not check them, so a separate type check is needed to fail the build on type errors.

What are @types packages?

Community-maintained type declarations from DefinitelyTyped for libraries that do not ship their own types.

What is the difference between @ts-ignore and @ts-expect-error?

Both suppress an error on the next line, but @ts-expect-error itself errors when the code no longer has an error, so stale suppressions are found.

Interview questions

How do you configure TypeScript for a project?

With tsconfig.json: enable strict, choose target and lib for the runtime, set module and moduleResolution for the bundler or Node.js, jsx for React, noEmit when a bundler transpiles, and include the source folders.

How would you migrate a large JavaScript codebase to TypeScript?

Enable allowJs, convert files gradually starting with leaf modules, add types for core data, install @types, enable strict flags progressively, use @ts-expect-error for temporary gaps and add type checking and lint rules to CI.

What does isolatedModules do?

It makes TypeScript report constructs that cannot be transpiled one file at a time, which is required by tools like Babel, esbuild and SWC that process files in isolation.

Summary

  • tsconfig.json sets strictness, language target, module system and file inclusion; always use strict.
  • Use moduleResolution: bundler with Vite and NodeNext with Node.js; noEmit when a bundler transpiles.
  • Types come from your code, shipped declarations, @types/* and your own .d.ts files.
  • Run tsc --noEmit in CI, use typescript-eslint, and migrate gradually with allowJs.

Going deeper

See how much of this you can explain

A free mock interview asks you new questions on TypeScript for JavaScript developers for Frontend Developer and scores every answer, with what to fix.