Lesson 3 of 8 · 11 min · The Node.js runtime
Node.js modules (CommonJS and ESM) and worker threads
What you will learn
- The two module systems: CommonJS and ES modules
- Choose and configure ESM with
package.json - npm basics: dependencies, scripts, lockfile, security
- Run CPU-heavy work with
worker_threadswithout blocking the server - Send messages, share memory and use a worker pool
In simple words
A Node.js program is made of many files that import each other and packages from npm. There are two ways to write those imports: the older require (CommonJS) and the modern import (ES modules). Separately, because Node.js has one main thread, heavy calculations would freeze the server; worker threads let you send such jobs to a helper thread and get the answer back.
Words to know
- CommonJS (CJS): the original Node.js module system using
require()andmodule.exports. - ES modules (ESM): the standard module system using
importandexport. - npm: the package manager and registry for JavaScript packages.
- Worker thread: an extra JavaScript thread with its own event loop, for CPU-heavy tasks.
CommonJS and ES modules
| CommonJS | ES modules | |
|---|---|---|
| Import | const fs = require("node:fs") |
import fs from "node:fs" |
| Export | module.exports = { add } |
export function add() {} |
| Loading | synchronous, dynamic | static, asynchronous |
| File extension | .js (default) or .cjs |
.mjs, or .js with "type": "module" |
__dirname and __filename |
provided | use import.meta.dirname and import.meta.filename (Node 20.11+) |
Top-level await |
no | yes |
| Strict mode | optional | always |
Choose with package.json:
{
"name": "shop-api",
"version": "1.0.0",
"type": "module",
"engines": { "node": ">=22" },
"scripts": {
"dev": "node --watch --env-file=.env src/server.js",
"start": "node src/server.js",
"test": "node --test"
},
"dependencies": { "express": "^5.0.0" },
"devDependencies": { "eslint": "^9.0.0" }
}
"type": "module" makes every .js file in the package an ES module. New projects should use ESM, matching browsers and TypeScript (the earlier modules lesson covers syntax). In ESM:
import express from "express"; // a package
import { add } from "./math.js"; // a relative file: the extension is required
import { readFile } from "node:fs/promises"; // a built-in with the node: prefix
import config from "./config.json" with { type: "json" }; // JSON with an import attribute
const settings = await loadSettings(); // top-level await
const here = import.meta.dirname;
Using a CommonJS-only package from ESM works (import pkg from "pkg", usually a default import). Using an ES module from CommonJS used to need await import(); recent Node.js versions can also require() ES modules that have no top-level await. Dual-format packages ship both builds through the exports field. If you hit interop errors ("Cannot use import statement outside a module", "require is not defined in ES module scope", "ERR_REQUIRE_ESM"), the cause is a mismatch between the file's type and its syntax.
npm essentials
npm init -y # create package.json
npm install express # add a dependency (saved with a ^ range)
npm install -D vitest # a development dependency
npm ci # clean, exact install from the lockfile (use in CI and Docker)
npm run dev # run a script
npx eslint . # run a tool without installing it globally
npm audit # check for known vulnerabilities
npm outdated # see newer versions
- Commit the lockfile (
package-lock.json): it pins exact versions of every dependency (including nested ones), so everyone and every build gets the same tree. - Semantic versioning:
^5.1.0allows minor and patch updates (5.x.x),~5.1.0only patches; major versions can break. dependenciesare needed at runtime;devDependenciesonly for building and testing (npm ci --omit=devin production images).- Supply-chain safety: packages run code on your machine and in production. Prefer well-known maintained packages, check weekly downloads, maintainers and recent releases, keep dependencies few, review new transitive dependencies, enable
npm auditand automated updates (Dependabot, Renovate), usenpm ci, be wary of install scripts, and consider two-factor authentication on your own npm account. Typosquatted names are a real attack. - Alternatives:
pnpm(fast, disk-efficient, strict) andyarnuse the same registry. - Monorepos: workspaces (
"workspaces"inpackage.json).
Why worker threads
One thread runs your JavaScript. A CPU-heavy job on it, such as resizing images, hashing large data, parsing a huge file, running a simulation, makes the whole server unresponsive. worker_threads runs JavaScript in separate threads, each with its own event loop and memory, so the main thread keeps serving requests. (I/O work does not need workers: it is already non-blocking.)
A worker
// main.js
import { Worker } from "node:worker_threads";
function runInWorker(numbers) {
return new Promise((resolve, reject) => {
const worker = new Worker(new URL("./sum-worker.js", import.meta.url), { workerData: { numbers } });
worker.once("message", resolve);
worker.once("error", reject);
worker.once("exit", (code) => { if (code !== 0) reject(new Error(`Worker stopped with exit code ${code}`)); });
});
}
const result = await runInWorker(Array.from({ length: 10_000_000 }, (_, i) => i));
console.log(result);
// sum-worker.js
import { parentPort, workerData } from "node:worker_threads";
let sum = 0;
for (const n of workerData.numbers) sum += n; // heavy work happens off the main thread
parentPort.postMessage(sum);
workerDatapasses the initial data (copied with the structured clone algorithm);parentPort.postMessagesends results back; the main thread listens formessage,errorandexit.- Messages are copied (not shared), so sending huge objects is itself costly. Use transferables (
ArrayBuffers moved, not copied) orSharedArrayBufferwithAtomicsfor shared memory (carefully; it brings data races). - A worker is relatively heavyweight (its own V8 isolate and memory, about tens of milliseconds to start), so do not create one per request: use a pool.
A worker pool
Libraries such as Piscina manage a fixed number of workers and a task queue:
import Piscina from "piscina";
const pool = new Piscina({
filename: new URL("./resize.js", import.meta.url).href,
maxThreads: 4, // about the number of CPU cores
});
app.post("/thumbnail", async (req, res) => {
const result = await pool.run({ path: req.body.path, width: 200 }); // queued if all workers are busy
res.json(result);
});
Size the pool to the number of cores (os.availableParallelism()), set a queue limit to apply back-pressure, and keep job data small.
Environment and testing
- Workers inherit the environment by default;
workerDataandenvoptions can customise. - Handle
errorevents or an uncaught exception in a worker just ends that worker, not the whole process. - Terminate workers when done (
worker.terminate()), and shut the pool down onSIGTERM. - Test the pure function that the worker runs in a normal unit test, and test the worker wiring with a small integration test.
Common mistakes
- Mixing
requireandimportin one file, or forgetting"type": "module". - Omitting file extensions in ESM imports.
- Not committing the lockfile or using
npm installinstead ofnpm ciin CI. - Putting every package in
dependencies(or runtime packages indevDependencies). - Installing unvetted packages.
- Creating a worker per request.
- Sending very large objects to workers instead of transferring buffers.
- Using workers for I/O, where they add nothing.
Try it yourself
- Create a project with
"type": "module", import a local module with its extension and a built-in withnode:. - Reproduce the
ERR_REQUIRE_ESMor "require is not defined" error and fix it. - Add a CPU-heavy function (for example, count primes up to 5 million) to a route; show that
/healthhangs, then move it to a worker. - Use Piscina to run the same job with a pool of 4 workers and send 20 requests.
- Run
npm auditandnpm outdatedin a project and decide what to update.
Check yourself
How do you make Node.js treat .js files as ES modules?
Set "type": "module" in the nearest package.json (or use the .mjs extension).
Why commit package-lock.json?
It pins exact versions of all dependencies, so installs are reproducible across machines and in CI (npm ci).
When should you use worker threads?
For CPU-bound work that would block the event loop; not for I/O, which is already asynchronous.
Why use a worker pool instead of creating a worker per task?
Starting a worker is expensive; a pool reuses a fixed number of workers and queues work, bounding memory and CPU use.
Interview questions
CommonJS versus ES modules in Node.js?
CommonJS uses require and module.exports, loads synchronously and is the legacy default; ES modules use import/export, are static and asynchronous, support top-level await and tree shaking, and are the standard shared with browsers. Choose with "type" in package.json.
How do you handle a CPU-intensive task in a Node.js server?
Offload it to worker threads (preferably through a pool), a child process, or a background queue with worker services, keeping the main event loop free; first confirm with profiling that it is the bottleneck.
What is the difference between worker_threads, child_process and cluster?
Worker threads run JavaScript in threads within one process and can share memory; child processes are separate OS processes with isolated memory; cluster forks processes that share a server port to use multiple cores.
Summary
- Prefer ES modules with
"type": "module", file extensions and thenode:prefix; know CommonJS for legacy code. - Use npm with a committed lockfile,
npm ci, careful dependency choices andnpm audit. - Use worker threads (in a pool) for CPU-heavy work; messages are copied, so transfer or share large buffers carefully.
- Measure first, and choose between workers, child processes, clustering and queues by the problem.
Going deeper
- Node.js: ECMAScript modules: ESM in Node.js and interoperability.
- Node.js: Modules (CommonJS):
requireandmodule.exports. - Node.js: Worker threads: the full API.
- npm documentation: commands,
package.jsonand lockfiles.
See how much of this you can explain
A free mock interview asks you new questions on Node.js and Express backends for Full Stack Developer and scores every answer, with what to fix.