Type-checked JavaScript for Node.js with CommonJS

Install

TypeScript is a development dependency: it checks your code and never runs in production. @types/node gives the checker the types of Node's built-in modules (node:fs, node:http, process and the rest). Pick the @types/node major version that matches the Node.js you run, for example @types/node@24 for Node.js 24.

npm install --save-dev typescript @types/node

jsconfig.json

Identical to the ES modules setup: nodenext takes the module format from package.json, so the same config checks either kind of project, and a project that mixes .cjs and .mjs files.

{
  "compilerOptions": {
    "checkJs": true,
    "noEmit": true,
    "strict": true,
    "module": "nodenext",
    "moduleResolution": "nodenext",
    "target": "es2024",
    "types": ["node"],
    "skipLibCheck": true
  },
  "include": ["src/**/*.js"]
}

npm scripts

"type": "commonjs" is also what Node.js assumes when there is no "type"; writing it makes the choice explicit, as Node.js's documentation recommends. lint checks once; lint:watch checks again on every save.

{
  "type": "commonjs",
  "scripts": {
    "lint": "tsc -p jsconfig.json",
    "lint:watch": "tsc -p jsconfig.json --watch --preserveWatchOutput"
  }
}

What the checker reads from require and module.exports

In a CommonJS .js file:

• const { formatPrice } = require("./format") is an import; a name the module does not export is an error, with a suggestion (TS2724), as below
• relative require calls may leave out .js, because Node.js tries the extension for CommonJS
• module.exports = { … } and exports.name = … are the module's exports, typed from the JSDoc on what you assign
• since TypeScript 5.8, require() of an ES module is allowed under nodenext, as in Node.js from 20.19 and 22.12; Node.js still refuses an ES module that uses top-level await

const { createServer } = require("node:http");
const { formatPrise } = require("./format");error TS2724: '"./format"' has no exported member named 'formatPrise'. Did you mean 'formatPrice'?

const port = Number(process.env.PORT ?? 3000);

createServer((req, res) => {
  res.end(`Today's special: ${formatPrise(1999)}`);
}).listen(port);

The example project

src/format.js exports a typed helper with module.exports; src/main.js requires it and Node's http module and starts a server.

const { createServer } = require("node:http");
const { formatPrice } = require("./format");

const port = Number(process.env.PORT ?? 3000);

createServer((req, res) => {
  res.end(`Today's special: ${formatPrice(1999)}`);
}).listen(port);

/**
 * @param {number} cents
 * @returns {string}
 */
function formatPrice(cents) {
  return `$${(cents / 100).toFixed(2)}`;
}

module.exports = { formatPrice };