The File System Module

Servers persist something — uploads, logs, settings, data. The Node.js for Beginners series now opens fs, Node's file system module: reading and writing text, appending and deleting, streaming large files without melting memory, and the JSON round-trip that chapter 16 will turn into a small database. Every technique here is the same one your favourite tools use — git, npm and your editor all store state in plain files.

Two flavours: sync and async

fs ships every operation in several styles. The pattern is uniform across the module.

Reading and writing files

import { writeFile, readFile } from 'node:fs/promises';

await writeFile('greeting.txt', 'Hello, files!\n', 'utf8');
await writeFile('greeting.txt', 'A second line\n', { flag: 'a' }); // append

const text = await readFile('greeting.txt', 'utf8');
console.log(text);

Expected output:

Hello, files!
A second line

• Always pass 'utf8' (or you get a Buffer — raw bytes that print as numbers).
• The default flag 'w' truncates; 'a' appends; 'wx' fails if the file exists (handy for locks).
• Missing file → the promise rejects with an error whose code is 'ENOENT'.
• For copying or moving, use the dedicated calls — copyFile and rename — instead of reading and writing by hand; they are faster and handle partial writes correctly.

Working with directories and metadata

import { mkdir, readdir, stat, unlink } from 'node:fs/promises';

await mkdir('data', { recursive: true });      // no error if it exists
const entries = await readdir('data');
console.log('entries:', entries);

const info = await stat('greeting.txt');
console.log('bytes:', info.size, 'isFile:', info.isFile());

await unlink('greeting.txt');                  // delete
console.log('deleted');

Expected output:

entries: [ 'todos.json' ]
bytes: 26 isFile: true
deleted

Every failure surfaces as a rejected promise with a machine-readable code: ENOENT (not found), EACCES (permissions), EISDIR (path is a directory). Branch on err.code, never on the message text.

Streams: large files without large memory

readFile loads the whole file into memory — fine for kilobytes, fatal for gigabytes. Streams process data in chunks as it flows.

import { createReadStream, createWriteStream } from 'node:fs';
import { pipeline } from 'node:stream/promises';

await pipeline(
  createReadStream('big-log.txt'),
  createWriteStream('big-log-copy.txt'),
);
console.log('copied with constant memory');

Expected output: copied with constant memory, with RAM use flat regardless of file size. Streams also power HTTP request and response bodies in chapter 11 — the same chunk-by-chunk model. Reach for them as soon as a file might be larger than you are happy to hold in RAM, and prefer pipeline over manually piping: it propagates errors and closes the streams for you, which hand-rolled chains routinely forget to do.

Reading and writing JSON (a preview of chapter 16)

import { readFile, writeFile } from 'node:fs/promises';

async function loadJSON(path, fallback = []) {
  try {
    return JSON.parse(await readFile(path, 'utf8'));
  } catch (err) {
    if (err.code === 'ENOENT') return fallback;
    throw err;                      // corrupt data must not vanish
  }
}

async function saveJSON(path, data) {
  await writeFile(path, JSON.stringify(data, null, 2) + '\n', 'utf8');
}

const todos = await loadJSON('data/todos.json');
await saveJSON('data/todos.json', [...todos, { id: 1, title: 'Learn fs', done: false }]);
console.log('stored', todos.length + 1, 'items');

Expected output: stored 1 items. Note the three rules baked in: a default for a missing file, a re-throw for unexpected errors, and pretty-printed JSON with a trailing newline so diffs stay readable.

Common mistakes

• Forgetting 'utf8' — you log a Buffer of byte numbers instead of text.
• readFileSync in a request handler — blocks the event loop for every connected client.
• Ignoring error codes — treating every failure as "file missing" hides permission and corruption bugs.
• Reading a huge file whole — use streams or readline once files approach memory limits.
• Write-then-crash loses data — overwrite patterns can truncate a file mid-write; write to a temp file and rename for critical data (chapter 16 does this).

Practice checklist

1. Write a script that creates a folder and three text files, then lists them with sizes.
2. Handle a deliberate ENOENT and print a friendly message instead of a stack trace.
3. Copy a file with streams and compare memory use against readFile/writeFile.
4. Build loadJSON/saveJSON helpers and round-trip an object of your own.
5. Append one line per run to a log file and open the result in an editor.

Files live in directories — which means paths, and paths deserve their own chapter. Next: Paths, Environment and Process.