Lesson 3 of 8 · 11 min · The Node.js runtime

Node.js modules (CommonJS and ESM) and worker threads

Covers: Node.js 22 and 24 LTS. Updated 13 Nov 2026. Part of the Full Stack Developer roadmap.

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_threads without 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() and module.exports.
  • ES modules (ESM): the standard module system using import and export.
  • 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.0 allows minor and patch updates (5.x.x), ~5.1.0 only patches; major versions can break.
  • dependencies are needed at runtime; devDependencies only for building and testing (npm ci --omit=dev in 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 audit and automated updates (Dependabot, Renovate), use npm 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) and yarn use the same registry.
  • Monorepos: workspaces ("workspaces" in package.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);
  • workerData passes the initial data (copied with the structured clone algorithm); parentPort.postMessage sends results back; the main thread listens for message, error and exit.
  • Messages are copied (not shared), so sending huge objects is itself costly. Use transferables (ArrayBuffers moved, not copied) or SharedArrayBuffer with Atomics for 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.

Workers versus other options

Option Use when
Worker threads CPU-bound work inside one Node.js process; share some memory
child_process (spawn, fork) run another program or a separate Node.js process; stronger isolation
cluster or several containers use all cores for request handling; each process has its own memory
A job queue (BullMQ, SQS) with worker services long-running or retryable background jobs, scheduled work
A native addon or another language extreme numeric performance
Do nothing special the work is I/O: promises are enough

Rules of thumb: measure first (event loop lag, profiling with node --prof or the Chrome DevTools profiler via --inspect), because the slow part is often a database query, not JavaScript. Workers have no access to the DOM (there is none) and do not share ordinary variables with the main thread; communication is by messages.

Environment and testing

  • Workers inherit the environment by default; workerData and env options can customise.
  • Handle error events 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 on SIGTERM.
  • 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 require and import in one file, or forgetting "type": "module".
  • Omitting file extensions in ESM imports.
  • Not committing the lockfile or using npm install instead of npm ci in CI.
  • Putting every package in dependencies (or runtime packages in devDependencies).
  • 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

  1. Create a project with "type": "module", import a local module with its extension and a built-in with node:.
  2. Reproduce the ERR_REQUIRE_ESM or "require is not defined" error and fix it.
  3. Add a CPU-heavy function (for example, count primes up to 5 million) to a route; show that /health hangs, then move it to a worker.
  4. Use Piscina to run the same job with a pool of 4 workers and send 20 requests.
  5. Run npm audit and npm outdated in 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 the node: prefix; know CommonJS for legacy code.
  • Use npm with a committed lockfile, npm ci, careful dependency choices and npm 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

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.