File System

Three flavours of the fs module

Node ships the same filesystem operations in three distinct APIs:

Style	Import	When to use
Callback (async)	import fs from 'node:fs'	Legacy code, Node streams
Synchronous	import fs from 'node:fs'	CLI scripts, startup-time config
Promise (async)	import fs from 'node:fs/promises'	All new server code

🟢 Prefer fs/promises in servers

fs.readFileSync and friends block the entire event loop — no other request can be handled while the OS reads the file. In a server process, always use the node:fs/promises API (or callback-based streams) so the event loop stays free to handle concurrent requests. The sync APIs are acceptable in CLI scripts or at process startup (before the server begins accepting requests).

Reading a file

Callback style

import fs from 'node:fs';

fs.writeFileSync('./hello.txt', 'Hello from Node.js!');

fs.readFile('./hello.txt', 'utf8', function(err, data) {
  if (err) throw err;
  console.log(data);
  fs.unlinkSync('./hello.txt');
});

Promise style (recommended)

Node.jsOpen in StackBlitz ▸

import { writeFile, readFile, readdir, rm } from 'node:fs/promises'; async function demo() { // Write a file await writeFile('/tmp/demo.txt', 'Hello from Node.js!', 'utf8'); console.log('Written: /tmp/demo.txt'); // Read it back var content = await readFile('/tmp/demo.txt', 'utf8'); console.log('Read back:', content); // List /tmp directory var entries = await readdir('/tmp'); console.log('Files in /tmp (first 5):', entries.slice(0, 5)); // Clean up await rm('/tmp/demo.txt'); console.log('Deleted /tmp/demo.txt'); } demo().catch(console.error);

Needs the Node.js runtime — open in StackBlitz to run.

Writing a file

writeFile creates the file if it does not exist and replaces the contents if it does. Use appendFile to add to an existing file.

Node.jsOpen in StackBlitz ▸

import { writeFile, appendFile, readFile, rm } from 'node:fs/promises'; async function demo() { var path = '/tmp/log.txt'; await writeFile(path, 'Line 1\n', 'utf8'); await appendFile(path, 'Line 2\n', 'utf8'); await appendFile(path, 'Line 3\n', 'utf8'); var result = await readFile(path, 'utf8'); console.log('File contents:'); console.log(result); await rm(path); } demo().catch(console.error);

Needs the Node.js runtime — open in StackBlitz to run.

Checking existence and stats

Node.jsOpen in StackBlitz ▸

import { stat, writeFile, rm } from 'node:fs/promises'; async function demo() { var path = '/tmp/stat-test.txt'; await writeFile(path, 'stat demo', 'utf8'); var info = await stat(path); console.log('size (bytes):', info.size); console.log('isFile:', info.isFile()); console.log('isDirectory:', info.isDirectory()); console.log('modified:', info.mtime.toISOString()); await rm(path); } demo().catch(console.error);

Needs the Node.js runtime — open in StackBlitz to run.

fs/promises vs sync — blocking the event loop

readFileSync does not just “read a file slower” — it runs to completion before anything else in the process can run, including a timer that was already scheduled with a 0 ms delay. readFile (promise-based) hands the read off and returns immediately, letting the rest of the synchronous code — and the event loop — keep moving while the read happens in the background:

Node.jsOpen in StackBlitz ▸

import { readFileSync, writeFileSync, unlinkSync } from 'node:fs'; import { readFile } from 'node:fs/promises'; var path = '/tmp/node-deep-dive-block-demo.txt'; writeFileSync(path, 'x'.repeat(5_000_000)); // ~5 MB — big enough to take real time to read // --- Sync: readFileSync runs to completion before anything else can -- // a pending timer cannot fire mid-read, no matter how short its delay --- var timerFired = false; setTimeout(function() { timerFired = true; }, 0); var syncData = readFileSync(path, 'utf8'); console.log('sync read length:', syncData.length); console.log('timer fired before readFileSync returned:', timerFired); // always false // --- Async: readFile returns a pending Promise immediately -- the very // next line of synchronous code always runs before the read settles --- var order = []; readFile(path, 'utf8').then(function() { order.push('read settled'); }); order.push('next line ran before the read settled'); console.log(order.join(' | ')); await readFile(path, 'utf8'); // let any pending read finish before cleanup unlinkSync(path);

Output (verified on Node 24)

sync read length: 5000000
timer fired before readFileSync returned: false
next line ran before the read settled

🟢 In a server, one readFileSync stalls every in-flight request

A single blocking read of a few milliseconds is invisible in a script. In a server handling concurrent requests, that same call freezes every connection — no request can be accepted, no response can be sent, no timer can fire — until the read returns. This is why node:fs/promises (or the callback API) is the rule for server code, and readFileSync is reserved for one-shot startup work before server.listen().

readFile vs streaming a large file — memory

readFile() (sync or promise) allocates one buffer holding the entire file. For a 50 MB file that means one 50 MB allocation, held in memory until you’re done with it. A stream instead delivers the file in bounded chunks — by default no more than highWaterMark (64 KiB) at a time — so memory use stays roughly constant regardless of file size:

Node.jsOpen in StackBlitz ▸

import { writeFileSync, unlinkSync, createReadStream } from 'node:fs'; import { readFile } from 'node:fs/promises'; var path = '/tmp/node-deep-dive-large.bin'; writeFileSync(path, Buffer.alloc(50 * 1024 * 1024)); // 50 MB fixture, all zero bytes // readFile: one allocation the size of the whole file var whole = await readFile(path); console.log('readFile() loaded bytes in one buffer:', whole.length); // stream: delivered in bounded highWaterMark-sized chunks, one at a time var chunkCount = 0; var maxChunk = 0; var total = 0; await new Promise(function(resolve, reject) { createReadStream(path) .on('data', function(chunk) { chunkCount++; total += chunk.length; if (chunk.length > maxChunk) maxChunk = chunk.length; }) .on('end', resolve) .on('error', reject); }); console.log('stream delivered bytes across', chunkCount, 'chunks'); console.log('largest single chunk (bytes):', maxChunk); console.log('total bytes match:', total === whole.length); unlinkSync(path);

Output (verified on Node 24)

readFile() loaded bytes in one buffer: 52428800
stream delivered bytes across 800 chunks
largest single chunk (bytes): 65536
total bytes match: true

For a 50 MB file, readFile needs one contiguous 50 MB allocation; the stream never holds more than 64 KiB at once — the difference that matters when the file could be gigabytes, or when hundreds of requests are reading files concurrently.

Globbing and cleanup in modern Node

Two newer APIs retire old dependencies. fs.glob (stable in Node 22+) replaces the glob package, and file handles support await using (Node 24+) so they close themselves:

import { writeFileSync, unlinkSync } from 'node:fs';
import { glob, open } from 'node:fs/promises';

writeFileSync('./config.json', JSON.stringify({ port: 3000 })); // demo fixture

// Find files without the `glob` package
for await (const file of glob('src/**/*.test.js')) {
  console.log(file);
}

// The handle is closed when the block exits — even if it throws
{
  await using fh = await open('./config.json');
  const text = await fh.readFile('utf8');
  console.log(JSON.parse(text).port);
}

unlinkSync('./config.json');

Synchronous reads — startup only

import { readFileSync, writeFileSync } from 'node:fs';

writeFileSync('./config.json', JSON.stringify({ port: 3000 })); // demo fixture

// Acceptable at startup — process has not yet started accepting requests
const config = JSON.parse(readFileSync('./config.json', 'utf8'));
console.log(config.port);

Never call readFileSync inside a request handler, route callback, or any function invoked after the server starts.

Mental Model

flowchart TB
  Call["fs call"] --> Sync["readFileSync / writeFileSync"]
  Call --> Async["readFile / writeFile (fs/promises)"]
  Sync -->|"runs to completion, no one else can run"| Blocks["blocks the event loop — every other request waits"]
  Async -->|"handed to the threadpool, returns a pending Promise"| Free["event loop keeps handling other work"]
  Blocks -->|"acceptable"| Startup["CLI scripts / before server.listen()"]
  Free -->|"required"| Server["server request handlers"]

sync fs calls run to completion and block everything else; async fs calls hand the work to the threadpool and return immediately

Trade-offs

Choice	Benefit	Cost
fs sync (readFileSync)	Simplest code — no callback, no await, no threadpool round-trip	Blocks the entire process for the duration of the call — unacceptable once a server is accepting requests
fs/promises (readFile)	Never blocks the event loop; composes with async/await	One extra threadpool hop per call — slightly higher latency than sync for a single call in a non-concurrent script
readFile() whole-file	Simplest possible code — one buffer, no event wiring	Memory use scales with file size; a 1 GB file needs a 1 GB buffer
createReadStream()	Constant memory regardless of file size; can start processing before the file finishes reading	More code — you handle 'data'/'end'/'error' (or use pipeline, covered in the streams module)

Common Misconceptions

• “readFileSync is just a slower readFile” — fact: the difference isn’t speed, it’s that readFileSync blocks the entire process — no timer, no other request, no I/O callback can run until it returns.
• “A quick readFileSync is fine because it only takes a few milliseconds” — fact: those milliseconds are stolen from every concurrent request the server is handling at that moment, not just the one that triggered the read.
• “readFile() and a stream use about the same memory since they read the same file” — fact: readFile() holds the whole file as one buffer; a stream holds at most one highWaterMark chunk (64 KiB by default) at a time, independent of total file size.

Reading AI-generated code

• Does a route handler or any function called after server.listen() use readFileSync, writeFileSync, or existsSync? Any of these blocks every concurrent request for the duration of the call.
• Does code load a potentially large or user-controlled file with readFile() into a single buffer, instead of streaming it, when the file will just be forwarded or processed chunk-by-chunk anyway?
• Does a file handle opened with fs.open()/fsPromises.open() get closed on every exit path, including thrown errors — or would await using (Node 24+) make that automatic?

🐛 Spot the bug

import { readFileSync } from 'node:fs';
import http from 'node:http';

var server = http.createServer(function(req, res) {
// reads the config file from disk on every single request
var config = JSON.parse(readFileSync('./config.json', 'utf8'));
res.end(JSON.stringify({ port: config.port }));
});

server.listen(3000);

Show the answer

readFileSync runs inside the request handler, so every incoming request blocks the entire event loop for the duration of the disk read — no other request can be accepted or answered while it runs, even ones that have nothing to do with this route. The fix is to read the config once at startup (before server.listen(), where a sync call is acceptable) and reuse the parsed object from a variable in every request, or use fs/promises’ readFile with a small in-memory cache if the file can change at runtime.

🟢 The one-line takeaway

fs/promises in anything that runs after server.listen(), fs sync only at startup — a blocking read doesn’t just slow down the request that triggered it, it freezes every other request the process is handling.

Why should you avoid fs.readFileSync inside a server request handler?

It requires a callback and cannot be used with async/await It blocks the event loop, preventing all other requests from being handled It is deprecated in Node 24+ It only works on Linux systems

What does fs.writeFile do if the target file already exists?

It throws an error — you must delete the file first It appends to the existing content It replaces the file contents entirely It creates a backup and writes to a new file

Which import gives you the promise-based fs API?

import fs from "node:fs" import fs from "node:fs/promises" import { promises } from "fs" — this is the only valid form import fs from "node:fs/async"

What does this print? var timerFired = false; setTimeout(() => { timerFired = true; }, 0); var data = readFileSync(path, "utf8"); console.log(timerFired);

true — 0 ms means the timer runs immediately false — readFileSync always runs to completion before any timer callback gets a turn It depends on file size undefined — timerFired is not defined yet

A 200 MB file is read once with fs.readFile() and once with fs.createReadStream(). Which statement about memory use is correct?

They use identical memory because they read the same bytes readFile() needs roughly one 200 MB allocation; the stream needs roughly one highWaterMark chunk (64 KiB by default) at a time The stream uses more memory because of the overhead of multiple data events readFile() uses less memory because it has no event listeners

What is wrong with calling readFileSync('./config.json') inside an HTTP request handler that runs on every request?

Nothing, as long as the file is small It throws MODULE_NOT_FOUND on the second call It blocks every other concurrent request for the duration of each read, on every single request It only works the first time the server starts

Submit

Mark as complete