How to configure TypeScript for Node.js

TypeScript configuration in a Node.js project controls how source files are type-checked and emitted as JavaScript for the runtime. A focused tsconfig.json keeps the compiler, package scripts, and Node.js module loader aligned before generated files are deployed or run.

Modern Node.js projects commonly pair NodeNext module output with an explicit "type": "module" package setting when source files use import and export. TypeScript then resolves package exports, built-in node: imports, and emitted file formats in the same style that Node.js uses at runtime.

Native Node.js TypeScript execution follows a different path. Recent Node.js releases can strip erasable type syntax from .ts files, but Node.js ignores tsconfig.json options that change emitted JavaScript, output directories, or path aliases; use tsc when the project needs a build directory, strict type checks, and JavaScript files that deployment tooling can run.

1. Confirm npm is reading the expected project.

   $ npm pkg get name
   "typescript-configure-demo"

   If the directory does not have package.json yet, initialize the project before adding TypeScript configuration.
   Related: How to create a Node.js project with npm

2. Install the TypeScript compiler and Node.js type definitions as development dependencies.

   $ npm install --save-dev typescript @types/node
   
   added 3 packages, and audited 4 packages in 2s
   
   found 0 vulnerabilities

   Use --save-dev for build and type-check tools that are not required by the running application.
   Related: How to install a Node.js dependency

3. Set the package to use ES modules.

   $ npm pkg set type=module

   Use this setting when the project source uses import and export syntax. Projects that intentionally stay on CommonJS should keep their package type unchanged and use .cts files or require()-style source where needed.
   Related: How to enable ES modules in Node.js

4. Add project scripts for type checking, building, and running the compiled output.

   $ npm pkg set scripts.build="tsc -p tsconfig.json" scripts.typecheck="tsc -p tsconfig.json --noEmit" scripts.start="node dist/index.js"

   Related: How to run package.json scripts in Node.js

5. Create tsconfig.json in the project root.

   tsconfig.json

   {
     "compilerOptions": {
       "target": "ES2022",
       "module": "NodeNext",
       "moduleResolution": "NodeNext",
       "rootDir": "src",
       "outDir": "dist",
       "strict": true,
       "types": ["node"],
       "sourceMap": true,
       "noEmitOnError": true,
       "skipLibCheck": true
     },
     "include": ["src/**/*.ts"],
     "exclude": ["dist", "node_modules"]
   }

   rootDir keeps TypeScript source under src, outDir writes compiled JavaScript under dist, and types loads Node.js globals and built-in module declarations from @types/node.

6. Create the source directory.

   $ mkdir -p src

7. Create src/index.ts or adapt an existing entry file under src.

   src/index.ts

   import { argv } from "node:process";
    
   const target: string = argv[2] ?? "Node.js";
   console.log(`TypeScript build ready for ${target}`);

8. Run the TypeScript type check without writing output files.

   $ npm run typecheck
   
   > typescript-configure-demo@1.0.0 typecheck
   > tsc -p tsconfig.json --noEmit

9. Build the project.

   $ npm run build
   
   > typescript-configure-demo@1.0.0 build
   > tsc -p tsconfig.json

10. Check the emitted files in dist.

    $ ls dist
    index.js
    index.js.map

11. Run the compiled JavaScript with Node.js.

    $ node dist/index.js Node.js
    TypeScript build ready for Node.js