Table of contents:
Is Node.js single-threaded?
Yes and no. Your JavaScript code runs on a single thread, the main thread, which runs the event loop. But Node.js itself is not single-threaded:
- libuv thread pool: a pool of 4 threads by default (configurable with the
UV_THREADPOOL_SIZEenvironment variable) that handles operations the operating system can't do asynchronously, such as file system (fs),dns.lookup, somecryptofunctions (pbkdf2,scrypt,randomBytes) andzlibcompression. - Operating system: network I/O (HTTP, TCP, database connections) doesn't use the thread pool. libuv delegates it to
the OS asynchronous APIs (
epollon Linux,kqueueon macOS,IOCPon Windows). - V8: uses background threads for garbage collection and compilation.
So, Node.js can handle thousands of concurrent I/O operations with a single JavaScript thread, because the main thread
only runs the callbacks when the work is done. When you need to run JavaScript in parallel, you can use
worker_threads, child_process, cluster, or run multiple instances of your application.
CPU-bound vs. I/O-bound tasks
Node.js executes your code in the call stack of the main thread. When a CPU-bound task is executed, it blocks the main thread: no other request, timer or callback runs until it finishes. So, a single heavy CPU-bound task can impact the performance of the whole application.
Examples of CPU operations:
- Mathematical computation
- Image, video and audio processing
- Compiling or parsing code (including
JSON.parse/JSON.stringifyof huge payloads) - Artificial Intelligence (e.g. running models locally)
- Regular expressions (especially vulnerable ones, see ReDoS)
- Cryptographic operations (e.g. hashing passwords)
When the task is I/O-bound, Node.js handles it asynchronously, without blocking the main thread: the work happens in the OS or in the libuv thread pool, and the callback runs when the result is ready.
Examples of I/O operations:
- Network operations (
fetch, HTTP, WebSockets) - Database operations
- File system operations
- Stream operations
- E-mail operations
- Timers and delayed executions (although these are not strictly I/O-bound, they are non-blocking and handled asynchronously)
Be careful with the synchronous versions of the Node.js APIs (functions ending with Sync): they block the main thread
even for I/O operations.
Don't do this:
import { readFileSync } from "node:fs";
import { createServer } from "node:http";
createServer( ( _req, res) => {
// blocks the main thread on every request
const file = readFileSync( "./report.json ", "utf-8") ;
res. end( file) ;
} ) . listen( 8000) ;
Do this instead:
import { readFile } from "node:fs/promises ";
import { createServer } from "node:http";
createServer( async ( _req, res) => {
// the main thread keeps handling other requests while the file is read
const file = await readFile( "./report.json ", "utf-8") ;
res. end( file) ;
} ) . listen( 8000) ;
Node.js event loop
The event loop orchestrates asynchronous (non-blocking I/O) operations and manages the flow of events in the application. It enables the application to continue executing other code while I/O operations are in progress, preventing blocking and enhancing performance.
When an asynchronous operation finishes, its callback is placed in a queue. When the call stack is empty, the event loop takes the next callback and runs it.
Event loop phases
The Node.js event loop (implemented by libuv) consists of 6 phases, and each phase has its own queue of callbacks:
- Timers: executes callbacks scheduled by
setTimeoutandsetInterval - Pending callbacks: executes some system callbacks deferred to the next loop iteration (e.g. TCP errors)
- Idle & prepare: only used internally
- Poll: retrieves new I/O events and executes their callbacks (most of your code runs here)
- Check: executes callbacks scheduled by
setImmediate - Close callbacks: executes close callbacks (e.g.
socket.on("close", ...))
When there is nothing else to do (no timers, no pending I/O, no active servers), the event loop ends and the process exits.
Detailed overview about the event loop here
Microtasks: process.nextTick and Promises
Besides the phases above (also known as the macrotasks), there are two microtask queues that are not part of libuv:
- nextTick queue: callbacks scheduled with
process.nextTick - Promise queue: Promise callbacks (
.then,.catch,await) andqueueMicrotask
Microtasks have higher priority: they run as soon as the current operation finishes,
after every single callback and before the event loop moves on. That's why an infinite chain of
Promises or process.nextTick can starve the event loop as well as a heavy CPU-bound task.
Example (order.cjs):
console. log( "1. sync ") ;
setTimeout( ( ) => console. log( "timeout") , 0) ;
setImmediate( ( ) => console. log( "immediate") ) ;
Promise. resolve( ) . then( ( ) => console. log( "promise") ) ;
process. nextTick( ( ) => console. log( "nextTick") ) ;
console. log( "2. sync ") ;
Output:
1. sync
2. sync
nextTick
promise
# timeout and immediate, in any order ( see below)
In CommonJS, the nextTick queue runs before the Promise queue. However, if you run the same code as an ES module
(.mjs, .ts with import, or "type": "module"), you will see promise before nextTick,
because the ES module itself is evaluated asynchronously, inside a Promise.
For new code, prefer queueMicrotask (a web standard) over process.nextTick.
setTimeout vs. setImmediate
In the main module, the order between setTimeout(callback, 0) and setImmediate is not guaranteed:
it depends on how fast the process starts. But inside an I/O callback, setImmediate always runs first,
because the check phase comes right after the poll phase.
Example:
const { readFile } = require( "node:fs") ;
readFile( __filename, ( ) => {
setTimeout( ( ) => console. log( "timeout") , 0) ;
setImmediate( ( ) => console. log( "immediate") ) ;
} ) ;
// always: immediate, timeout
Don't block the event loop
The golden rule of Node.js: the main thread should only orchestrate work, not do heavy work. If a single request takes 200ms of CPU, every other request waits 200ms.
Measuring the event loop delay
You can measure how much the event loop is being delayed with monitorEventLoopDelay.
Exporting this metric to your monitoring tool (e.g. OpenTelemetry, Prometheus) is a good practice.
import { monitorEventLoopDelay } from "node:perf_hooks";
const histogram = monitorEventLoopDelay( { resolution: 20 } ) ;
histogram. enable( ) ;
setInterval( ( ) => {
// values are in nanoseconds
const p99 = histogram. percentile( 99) / 1e6;
console. log( `Event loop delay p99: ${ p99. toFixed( 2) } ms`) ;
histogram. reset( ) ;
} , 5_000) . unref( ) ;
Splitting heavy work
If you have a long loop that can't be moved to another thread, you can split it into chunks and yield to the event loop
between them with setImmediate from node:timers/promises, so other callbacks have a chance to run.
Don't do this:
function processAll( items: Item[ ] ) {
// 1 million items blocks the main thread until the end
for ( const item of items) {
processItem( item) ;
}
}
Do this instead:
import { setImmediate } from "node:timers/promises ";
async function processAll( items: Item[ ] , chunkSize = 1_000) {
for ( let i = 0; i < items. length; i + = chunkSize) {
for ( const item of items. slice( i, i + chunkSize) ) {
processItem( item) ;
}
// lets the event loop handle other requests before the next chunk
await setImmediate( ) ;
}
}
This doesn't make the work faster, it only keeps the application responsive. For really heavy work, use worker_threads.
Node.js worker_threads
Worker threads run JavaScript in parallel, in the same process. Each worker has its own V8 instance and its own event loop, and they communicate with messages. This is the recommended way to run CPU-bound JavaScript code without blocking the main thread.
Example:
import { Worker, isMainThread, parentPort, workerData } from "node:worker_threads";
// CPU-bound task: calculating the fibonacci sequence
function fibonacci( n: number) : number {
if ( n <= 1) return n;
return fibonacci( n - 1) + fibonacci( n - 2) ;
}
function runInWorker( n: number) {
return new Promise<number>( ( resolve, reject) => {
// runs this same file in a new thread
const worker = new Worker( import. meta. filename, { workerData: n } ) ;
worker. once( "message", resolve) ;
worker. once( "error", reject) ;
} ) ;
}
if ( isMainThread) {
console. log( "Main thread is free to handle other tasks") ;
const result = await runInWorker( 45) ;
console. log( `Result from worker: ${ result} `) ;
} else {
// worker thread: has its own event loop
parentPort? . postMessage( fibonacci( workerData) ) ;
}
Creating a worker has a cost (startup time and its own memory), so don't create one per request. In real applications, use a pool of workers, such as Piscina.
Node.js child_process
You can use child_process to spawn separate processes, each one with its own memory.
Nowadays, it is mostly used to run other programs (e.g. ffmpeg, git, Python scripts),
while worker_threads is preferred for CPU-bound JavaScript.
Example:
import { execFile } from "node:child_process";
import { promisify } from "node:util";
const execFileAsync = promisify( execFile) ;
// converting a video with ffmpeg without blocking the main thread
const { stdout } = await execFileAsync( "ffmpeg", [ "-i", "input.mp4 ", "output.webm "] ) ;
Prefer execFile or spawn over exec: exec runs the command inside a shell,
so passing user input to it can lead to command injection.
You can also use fork to run another Node.js file, with a built-in message channel between the processes:
import { fork } from "node:child_process";
const child = fork( "./child.ts ") ;
child. on( "message", ( result) => {
console. log( `Result from child process: ${ result} `) ;
} ) ;
child. send( "start") ;
child.ts:
function fibonacci( n: number) : number {
if ( n <= 1) return n;
return fibonacci( n - 1) + fibonacci( n - 2) ;
}
process. on( "message", ( message) => {
if ( message === "start") {
process. send? .( fibonacci( 45) ) ;
process. exit( 0) ;
}
} ) ;
Recent Node.js versions run .ts files natively (type stripping), so you don't need ts-node or a build step for these examples.
Node.js cluster
You can use Node.js cluster to take advantage of multi-core systems by creating multiple instances (processes)
of the same application. Unlike child_process, it is made for scaling servers: all workers share the same port,
and the primary process distributes the connections between them.
Example:
import cluster from "node:cluster";
import { createServer } from "node:http";
import { availableParallelism } from "node:os";
if ( cluster. isPrimary) {
console. log( `Primary PID ${ process. pid} is running`) ;
// availableParallelism is the recommended replacement for cpus().length
for ( let i = 0; i < availableParallelism( ) ; i+ + ) {
cluster. fork( ) ;
}
cluster. on( "exit", ( worker) => {
console. log( `Worker PID ${ worker. process. pid} died, starting a new one `) ;
cluster. fork( ) ;
} ) ;
} else {
const server = createServer( ( _req, res) => {
res. end( `Hello World from PID ${ process. pid} \n`) ;
} ) ;
server. listen( 8000, ( ) => {
console. log( `Worker PID ${ process. pid} started`) ;
} ) ;
process. on( "SIGTERM", ( ) => {
console. log( `Worker PID ${ process. pid} is shutting down... `) ;
// stops accepting new connections and waits for the current ones
server. close( ( ) => process. exit( 0) ) ;
} ) ;
}
Scaling in production: PM2 and containers
PM2
If you deploy to a virtual machine, PM2 is a process manager that keeps your application
online 24/7. It provides process management, monitoring, log management and a built-in cluster mode,
so you don't need to write the cluster code yourself.
npm install pm2 -g
pm2 start app. js --name app_name -i max
--name app_namespecifies the application's name-i maxstarts one instance per available CPU core
Containers
If you deploy with Docker and Kubernetes (or a platform like Railway, Fly.io, AWS ECS or Cloud Run),
the common approach is one Node.js process per container: the platform restarts it when it crashes and
scales it horizontally by adding more containers (replicas), instead of using cluster or PM2 inside the container.
In both cases, always handle the SIGTERM signal to finish the current requests before shutting down (graceful shutdown).
When to use Node.js and when to avoid it
Node.js is very performant at handling I/O-bound operations, but it can struggle with CPU-bound tasks, as they block the event loop and degrade the performance of the whole application.
Node.js is highly recommended for I/O-heavy workloads, such as:
- API servers and BFFs (Backend for Frontend)
- Real-time applications (chats, WebSockets, notifications)
- Data streaming services
- Applications that call other services and AI APIs, where most of the time is spent waiting for the network
- Full-stack applications sharing TypeScript between the frontend and the backend
If your application has some CPU-bound tasks, you can move them to worker_threads (with a pool),
or to a background job queue processed by separate workers.
If CPU-intensive work is the core of your application (e.g. video encoding, heavy data processing, machine learning),
consider a dedicated service implemented in a language better suited for the job, such as Go, Rust or Python.