Lesson 4 of 4 · 12 min · TypeScript fundamentals
tsconfig.json, tooling and migrating to TypeScript
What you will learn
- What
tsconfig.jsondoes 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:
@typespackages,.d.tsfiles,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 asstrict. - 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.
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 theirpackage.json). - DefinitelyTyped:
npm install -D @types/lodashadds 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.tsfile 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 withdeclare 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-eslintadds 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/expectTypeOfcan test types. - Project references (
"references",tsc -b) split large repositories into separately built projects, speeding up builds. - Performance: keep
includetight, enableskipLibCheck, useincremental, avoid enormously complex types. - Use
npx tsc --showConfigto see the final merged configuration, and--explainFilesto learn why a file is included.
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
strictleft off or turned off to make errors disappear.- Not running
tsc --noEmitin CI, because the bundler does not check types. - Using
@ts-ignorefreely. - Mismatched
moduleandmoduleResolution. - Including
DOMin a Node.js project (or forgetting it in a browser one). - Path aliases configured in
tsconfigbut not in the bundler. - Forgetting
@types/node.
Try it yourself
- Create a project, run
npx tsc --init, set the strict options above and check a few files. - Add a
typecheckscript and make a pull request check fail on a type error. - Install
@types/nodeand@types/expressand see the errors disappear. - Add an import alias
@/*in bothtsconfig.jsonand the Vite config. - 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.jsonsets strictness, language target, module system and file inclusion; always usestrict.- Use
moduleResolution: bundlerwith Vite andNodeNextwith Node.js;noEmitwhen a bundler transpiles. - Types come from your code, shipped declarations,
@types/*and your own.d.tsfiles. - Run
tsc --noEmitin CI, usetypescript-eslint, and migrate gradually withallowJs.
Going deeper
- TSConfig reference: every option, with defaults and recommendations.
- TypeScript Handbook: What is a tsconfig.json: how the file works.
- TypeScript: Migrating from JavaScript: the official migration guide.
- TypeScript: Declaration files: writing and consuming
.d.tsfiles.
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.