fs and fs/promises

node:fs and node:fs/promises read, write, and stream files on disk - promise APIs for async work, streams for scale, and explicit flags for security-sensitive reads and writes.

Recipe

import { readFile, writeFile, mkdir } from 'node:fs/promises';
import { createReadStream } from 'node:fs';
 
await mkdir('data', { recursive: true });
await writeFile('data/out.json', JSON.stringify({ ok: true }));
const text = await readFile('data/out.json', 'utf8');

When to reach for this:

• Loading config at startup (small JSON)
• Streaming CSV export to HTTP response
• Writing uploaded temp files before virus scan
• Rotating log files to disk in workers

Working Example

import { open, writeFile, rename } from 'node:fs/promises';
import { createReadStream } from 'node:fs';
import { pipeline } from 'node:stream/promises';
import { createGzip } from 'node:zlib';
import { createWriteStream } from 'node:fs';
 
async function atomicWrite(path: string, data: string): Promise<void> {
  const tmp = `${path}.tmp`;
  await writeFile(tmp, data, { encoding: 'utf8', mode: 0o600 });
  await rename(tmp, path);
}
 
async function tailBytes(path: string, max: number): Promise<Buffer> {
  const handle = await open(path, 'r');
  try {
    const stat = await handle.stat();
    const size = stat.size;
    const start = Math.max(0, size - max);
    const len = size - start;
    const buf = Buffer.alloc(len);
    await handle.read(buf, 0, len, start);
    return buf;
  } finally {
    await handle.close();
  }
}
 
await pipeline(createReadStream('large.log'), createGzip(), createWriteStream('large.log.gz'));

What this demonstrates:

• Atomic write via temp file + rename reduces partial-write corruption
• filehandle.read reads tail segment without loading whole file
• pipeline + createReadStream compresses large logs with bounded memory
• File mode 0o600 for sensitive config on Unix

Deep Dive

How It Works

• libuv thread pool runs some fs operations - heavy sync fs still blocks loop if sync API used.
• File descriptors - open/filehandle pattern for positioned reads/writes.
• Flags - 'r', 'w', 'a', 'wx' exclusive create - prevent accidental overwrite.
• watch - fs.watch / fs.promises.watch - debounce in dev tools; prefer explicit reload signals in prod.

API Choice

TypeScript Notes

import { access, constants } from 'node:fs/promises';
 
await access('/path/to/file', constants.R_OK);

Gotchas

• readFileSync in HTTP handler - blocks event loop. Fix: fs/promises or streams.
• Path traversal - user supplies ../../etc/passwd. Fix: resolve under base directory.
• Watching thousands of files - EMFILE and CPU. Fix: narrow watch scope or use build tool.
• Default UTF-8 on binary files - corruption. Fix: omit encoding for Buffer.
• Not closing file handles - EMFILE leaks. Fix: try/finally with close().

Alternatives

FAQs

Related

• path and url - safe path join
• Streams Basics - createReadStream
• Buffer Security - file permissions
• Built-in APIs Basics - overview

Stack versions: This page was written for Node.js 24.18.0 (Active LTS), npm 10+, TypeScript 5.6+, Express 5, Fastify 5, and NestJS 11.