fs — File System

Reading, writing, and manipulating files and directories in Node.js — fs/promises, streams, watching files, and common patterns.

What it is, in plain English: The fs module (built into Node.js) provides APIs for working with the file system. Use fs/promises for async file operations with async/await. readFile() reads an entire file into memory. writeFile() writes or creates a file. For large files, use streams (createReadStream/createWriteStream) to process data incrementally. fs.watch() monitors files for changes.

Where this bites you

A relative path like "config.json" is resolved against the folder you ran node from (process.cwd()), not the folder the script lives in. The same script works when you cd src && node app.js and fails with ENOENT when you run node src/app.js from the project root, which is exactly how npm scripts, cron jobs and Docker containers run it.

// src/app.js -- config.json sits right next to this file
import { readFile } from "fs/promises";

const conf = JSON.parse(await readFile("config.json", "utf-8"));   // relative to... where?
console.log("port:", conf.port);
// $ cd src && node app.js        -> port: 8080
// $ node src/app.js              (from the project root)
// Error: ENOENT: no such file or directory, open 'config.json'

Reading and writing files in Node.js

Node.js only. The fs module doesn't exist in browsers — use browser storage APIs (localStorage, IndexedDB, File System Access API) there.

Import the module

// ESM (recommended — .mjs files or "type": "module" in package.json):
import { readFile, writeFile, mkdir, readdir, stat, unlink, rename } from "fs/promises";
import { existsSync } from "fs";  // sync version (ok for startup checks)

// CommonJS (.js files without "type": "module"):
const { readFile, writeFile } = require("fs/promises");

Reading files

// Read as string:
const text = await readFile("notes.txt", "utf-8");
console.log(text);

// Read JSON:
const raw  = await readFile("config.json", "utf-8");
const conf = JSON.parse(raw);
console.log(conf.port);  // 3000

// Read as Buffer (binary — images, PDFs etc.):
const bytes = await readFile("photo.jpg");  // no encoding = Buffer
console.log(bytes.byteLength, "bytes");

// Handle missing files:
try {
  const data = await readFile("missing.txt", "utf-8");
} catch (e) {
  if (e.code === "ENOENT") console.log("File not found");
  else throw e;  // something unexpected — re-throw
}

The examples above assume the files are in the current working directory. For files that belong to your code, build the path from the script's own location. new URL("config.json", import.meta.url) does it in one step, and fs functions accept the URL directly. (In CommonJS, use path.join(__dirname, "config.json").)

// src/app.js
import { readFile } from "fs/promises";

const configUrl = new URL("config.json", import.meta.url);   // relative to THIS file
const conf = JSON.parse(await readFile(configUrl, "utf-8"));
console.log("port:", conf.port);
// $ cd src && node app.js        -> port: 8080
// $ node src/app.js              -> port: 8080

Writing files

// Write string (creates file if it doesn't exist, overwrites if it does):
await writeFile("output.txt", "Hello, World!", "utf-8");

// Write JSON:
const data = { name: "Alice", score: 95 };
await writeFile("user.json", JSON.stringify(data, null, 2));

// Append (add to end of file):
import { appendFile } from "fs/promises";
await appendFile("log.txt", `[${new Date().toISOString()}] Server started
`);

Directories

// Create directory (including parents):
await mkdir("dist/css/fonts", { recursive: true });  // won't throw if exists

// List directory:
const files = await readdir("./src");
console.log(files);  // ["app.js", "utils.js", "style.css"]

// Filter to only JS files:
const jsFiles = files.filter(f => f.endsWith(".js"));

// Delete a file:
await unlink("old-file.txt");

// Rename / move:
await rename("old-name.txt", "new-name.txt");
await rename("file.txt", "archive/file.txt");  // also moves across dirs

Try It Yourself

// fs module — Node.js file system (runs in Node.js, not browser)
// This demo shows the patterns — run in Node.js to see real output

// Import (two equivalent styles):
// import { readFile, writeFile, mkdir } from "fs/promises";  // ESM
// const { readFile, writeFile } = require("fs/promises");    // CJS

// ─── READING FILES ───────────────────────────────────────────────────────────

// Read entire file as string:
// const content = await readFile("data.txt", "utf-8");
// console.log(content);

// Read as Buffer (binary):
// const buffer = await readFile("image.png");
// console.log(buffer.byteLength, "bytes");

// ─── WRITING FILES ───────────────────────────────────────────────────────────

// Write (create or overwrite):
// await writeFile("output.txt", "Hello, World!", "utf-8");

// Append:
// await appendFile("log.txt", `[${new Date().toISOString()}] Event\n`);

// Write JSON:
const data = { users: ["Alice", "Bob"], count: 2 };
// await writeFile("data.json", JSON.stringify(data, null, 2));

// ─── DIRECTORIES ─────────────────────────────────────────────────────────────

// Create directory (and parents):
// await mkdir("dist/css/fonts", { recursive: true });

// List directory:
// const files = await readdir("./src");
// const onlyJS = files.filter(f => f.endsWith(".js"));

// ─── FILE INFO ───────────────────────────────────────────────────────────────

// Check if file exists (sync, good for startup checks):
// const exists = existsSync("config.json");

// Get file stats:
// const info = await stat("data.txt");
// console.log("Size:", info.size, "bytes");
// console.log("Modified:", info.mtime);
// console.log("Is directory:", info.isDirectory());

// ─── COMMON PATTERNS ─────────────────────────────────────────────────────────

// Safe read with fallback:
async function readJSON(path, fallback = {}) {
  try {
    const text = await (await import("fs/promises")).readFile(path, "utf-8").catch(() => null);
    return text ? JSON.parse(text) : fallback;
  } catch {
    return fallback;
  }
}

// Atomic write (write to temp, rename to final — prevents partial writes):
async function atomicWrite(path, content) {
  const tmp = path + ".tmp." + Date.now();
  const fs  = await import("fs/promises");
  await fs.writeFile(tmp, content, "utf-8");
  await fs.rename(tmp, path);  // rename is atomic on most OSes
}

console.log("fs patterns shown — run in Node.js to use file system");
console.log("Import: import { readFile, writeFile } from 'fs/promises'");

Streams, file watching, and common patterns

Streams — for large files

import { createReadStream, createWriteStream } from "fs";
import { createGzip } from "zlib";
import { pipeline }   from "stream/promises";

// Read a large file line by line (memory-efficient):
import { createInterface } from "readline";
const rl = createInterface({
  input:     createReadStream("large.csv"),
  crlfDelay: Infinity,
});
let lineCount = 0;
for await (const line of rl) {
  processLine(line);
  lineCount++;
}
console.log(`Processed ${lineCount} lines`);

// Compress a file without loading it into memory:
await pipeline(
  createReadStream("data.log"),
  createGzip(),
  createWriteStream("data.log.gz")
);

File watching

import { watch } from "fs";

// Watch a file for changes:
const watcher = watch("config.json", (eventType, filename) => {
  console.log(`${filename} changed (${eventType})`);  // "change" or "rename"
  reloadConfig();
});

// Watch a directory:
const dirWatcher = watch("./src", { recursive: true }, (eventType, filename) => {
  if (filename?.endsWith(".js")) {
    console.log("JS file changed:", filename);
    rebuild();
  }
});

// Stop watching:
setTimeout(() => watcher.close(), 60000);

Atomic write and safe patterns

// ATOMIC WRITE — prevents corrupt files if process crashes mid-write:
async function atomicWrite(path, content) {
  const tmp = `${path}.tmp.${process.pid}.${Date.now()}`;
  try {
    await writeFile(tmp, content, "utf-8");
    await rename(tmp, path);  // atomic on POSIX (not always on Windows)
  } catch (e) {
    await unlink(tmp).catch(() => {});  // clean up temp file
    throw e;
  }
}

// SAFE JSON READ with fallback:
async function readJSON(path, fallback = null) {
  try {
    return JSON.parse(await readFile(path, "utf-8"));
  } catch (e) {
    if (e.code === "ENOENT") return fallback;  // file missing
    if (e instanceof SyntaxError) return fallback;  // invalid JSON
    throw e;
  }
}

// WALK DIRECTORY RECURSIVELY:
async function* walkDir(dir) {
  for (const entry of await readdir(dir, { withFileTypes: true })) {
    const full = `${dir}/${entry.name}`;
    if (entry.isDirectory()) yield* walkDir(full);
    else yield full;
  }
}

for await (const file of walkDir("./src")) {
  console.log(file);  // prints every file recursively
}

fs spec, error codes, and sync vs async

POSIX error codes you'll encounter

// Every fs error has a .code property:
try {
  await readFile("missing.txt", "utf-8");
} catch (e) {
  switch (e.code) {
    case "ENOENT":  // No such file or directory
    case "EACCES":  // Permission denied
    case "EEXIST":  // File already exists
    case "EISDIR":  // Expected file, got directory
    case "ENOTDIR": // Expected directory, got file
    case "ENOTEMPTY": // Directory not empty (rmdir)
    case "EMFILE":  // Too many open files
    case "ENOSPC":  // No space left on device
  }
}

When to use sync vs async

// Sync (readFileSync, writeFileSync etc.) — blocks the event loop!
// OK for: startup/init code, CLI scripts, tests
// NEVER for: request handlers, concurrent operations

// Startup config (sync is fine — happens once before server starts):
import { readFileSync, existsSync } from "fs";
const config = existsSync("config.json")
  ? JSON.parse(readFileSync("config.json", "utf-8"))
  : { port: 3000 };

// Request handler — MUST be async:
app.get("/data", async (req, res) => {
  const data = await readFile("data.json", "utf-8");  // non-blocking
  res.send(data);
});

fs spec — Node.js docs §fs

The Node.js fs module wraps POSIX system calls (open, read, write, close, stat, mkdir, etc.) via libuv's thread pool (default 4 threads). The async versions are truly non-blocking — they queue I/O operations to libuv's I/O thread pool and callback/resolve on completion. fs.promises (available since Node.js 10) returns Promises instead of using callbacks. fs/promises import (Node.js 14+) is the recommended modern form. File descriptors (from fs.open()) must be explicitly closed with fs.close() to prevent file descriptor leaks.

Official Sources

The Codex links only to official documentation and the ECMAScript specification. No third-party tutorials.