Node.js fs Module Guide

The fs module provides APIs for interacting with the file system. Here's how to use it effectively.

Import Methods#

// Promise-based API (recommended)
import { readFile, writeFile } from 'node:fs/promises';

// Callback-based API
import { readFile, writeFile } from 'node:fs';

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

// Full module
import * as fs from 'node:fs/promises';

Reading Files#

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

// Read text file
const content = await readFile('file.txt', 'utf8');
console.log(content);

// Read as buffer
const buffer = await readFile('image.png');
console.log(buffer.length, 'bytes');

// With error handling
try {
  const data = await readFile('config.json', 'utf8');
  const config = JSON.parse(data);
} catch (error) {
  if (error.code === 'ENOENT') {
    console.log('File not found');
  } else {
    throw error;
  }
}

// Read JSON directly
import { readFile } from 'node:fs/promises';

async function readJson(path) {
  const content = await readFile(path, 'utf8');
  return JSON.parse(content);
}

Writing Files#

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

// Write text file
await writeFile('output.txt', 'Hello, World!', 'utf8');

// Write JSON
const data = { name: 'John', age: 30 };
await writeFile('data.json', JSON.stringify(data, null, 2));

// Append to file
await appendFile('log.txt', `${new Date().toISOString()} - Event\n`);

// Write with options
await writeFile('file.txt', content, {
  encoding: 'utf8',
  mode: 0o644,
  flag: 'w', // 'a' for append, 'wx' for exclusive write
});

// Write buffer
const buffer = Buffer.from([0x48, 0x65, 0x6c, 0x6c, 0x6f]);
await writeFile('binary.bin', buffer);

Directory Operations#

import { mkdir, readdir, rmdir, rm } from 'node:fs/promises';

// Create directory
await mkdir('new-folder');

// Create nested directories
await mkdir('path/to/nested/folder', { recursive: true });

// Read directory
const files = await readdir('src');
console.log(files); // ['index.js', 'utils.js', ...]

// Read with file types
const entries = await readdir('src', { withFileTypes: true });
for (const entry of entries) {
  if (entry.isDirectory()) {
    console.log('Dir:', entry.name);
  } else if (entry.isFile()) {
    console.log('File:', entry.name);
  }
}

// Remove empty directory
await rmdir('empty-folder');

// Remove directory recursively
await rm('folder', { recursive: true, force: true });

File Information#

import { stat, lstat, access, constants } from 'node:fs/promises';

// Get file stats
const stats = await stat('file.txt');
console.log({
  size: stats.size,
  isFile: stats.isFile(),
  isDirectory: stats.isDirectory(),
  created: stats.birthtime,
  modified: stats.mtime,
  permissions: stats.mode,
});

// Check if path exists
async function exists(path) {
  try {
    await access(path);
    return true;
  } catch {
    return false;
  }
}

// Check permissions
async function canWrite(path) {
  try {
    await access(path, constants.W_OK);
    return true;
  } catch {
    return false;
  }
}

// lstat doesn't follow symlinks
const linkStats = await lstat('symlink');
console.log(linkStats.isSymbolicLink());

Copy, Move, Rename#

import { copyFile, rename, cp } from 'node:fs/promises';

// Copy file
await copyFile('source.txt', 'destination.txt');

// Copy with flags
import { constants } from 'node:fs';
await copyFile('src.txt', 'dest.txt', constants.COPYFILE_EXCL);

// Rename/move file
await rename('old-name.txt', 'new-name.txt');
await rename('file.txt', 'other-folder/file.txt');

// Copy directory recursively (Node 16.7+)
await cp('src-folder', 'dest-folder', { recursive: true });

Streams#

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

// Read large file with stream
const readStream = createReadStream('large-file.txt', 'utf8');

for await (const chunk of readStream) {
  console.log('Chunk:', chunk.length);
}

// Write with stream
const writeStream = createWriteStream('output.txt');
writeStream.write('Line 1\n');
writeStream.write('Line 2\n');
writeStream.end();

// Copy with streams (memory efficient)
await pipeline(
  createReadStream('source.txt'),
  createWriteStream('destination.txt')
);

// Process large file line by line
import { createInterface } from 'node:readline';

const rl = createInterface({
  input: createReadStream('large-file.txt'),
  crlfDelay: Infinity,
});

for await (const line of rl) {
  console.log(line);
}

Watching Files#

import { watch } from 'node:fs/promises';

// Watch for changes
const watcher = watch('src', { recursive: true });

for await (const event of watcher) {
  console.log(`${event.eventType}: ${event.filename}`);
}

// With AbortController
const ac = new AbortController();

setTimeout(() => ac.abort(), 10000); // Stop after 10s

try {
  const watcher = watch('src', { signal: ac.signal });
  for await (const event of watcher) {
    console.log(event);
  }
} catch (error) {
  if (error.name === 'AbortError') {
    console.log('Stopped watching');
  }
}

Symbolic Links#

import { symlink, readlink, realpath } from 'node:fs/promises';

// Create symlink
await symlink('target-file.txt', 'link-name.txt');

// Create directory symlink
await symlink('target-dir', 'link-dir', 'dir');

// Read symlink target
const target = await readlink('link-name.txt');
console.log('Points to:', target);

// Get real path (resolve symlinks)
const real = await realpath('link-name.txt');
console.log('Real path:', real);

Temporary Files#

import { mkdtemp, writeFile, rm } from 'node:fs/promises';
import { tmpdir } from 'node:os';
import { join } from 'node:path';

// Create temp directory
const tempDir = await mkdtemp(join(tmpdir(), 'myapp-'));
console.log('Temp dir:', tempDir);

try {
  // Use temp directory
  await writeFile(join(tempDir, 'data.txt'), 'temporary data');

  // Process files...
} finally {
  // Clean up
  await rm(tempDir, { recursive: true });
}

File Handles#

import { open } from 'node:fs/promises';

// Open file handle
const handle = await open('file.txt', 'r+');

try {
  // Read from specific position
  const buffer = Buffer.alloc(100);
  const { bytesRead } = await handle.read(buffer, 0, 100, 0);

  // Write at specific position
  await handle.write('Hello', 0);

  // Get stats
  const stats = await handle.stat();

  // Truncate
  await handle.truncate(1000);

  // Sync to disk
  await handle.sync();
} finally {
  await handle.close();
}

// Using with syntax
import { open } from 'node:fs/promises';

const file = await open('file.txt', 'r');
try {
  const content = await file.readFile('utf8');
} finally {
  await file.close();
}

Recursive Operations#

import { readdir, stat, rm } from 'node:fs/promises';
import { join } from 'node:path';

// Get all files recursively
async function* getFiles(dir) {
  const entries = await readdir(dir, { withFileTypes: true });

  for (const entry of entries) {
    const path = join(dir, entry.name);
    if (entry.isDirectory()) {
      yield* getFiles(path);
    } else {
      yield path;
    }
  }
}

// Usage
for await (const file of getFiles('src')) {
  console.log(file);
}

// Get directory size
async function getDirSize(dir) {
  let size = 0;
  for await (const file of getFiles(dir)) {
    const stats = await stat(file);
    size += stats.size;
  }
  return size;
}

Permissions#

import { chmod, chown } from 'node:fs/promises';

// Change permissions
await chmod('script.sh', 0o755); // rwxr-xr-x
await chmod('secret.txt', 0o600); // rw-------

// Change owner (requires privileges)
await chown('file.txt', uid, gid);

// Permission constants
import { constants } from 'node:fs';
// constants.S_IRUSR - owner read
// constants.S_IWUSR - owner write
// constants.S_IXUSR - owner execute

Best Practices#

API Choice:
✓ Use promises API (fs/promises)
✓ Use streams for large files
✓ Avoid sync methods in servers
✓ Use file handles for complex ops

Error Handling:
✓ Check error.code (ENOENT, etc.)
✓ Handle EACCES (permission denied)
✓ Use try/finally for cleanup
✓ Validate paths before operations

Performance:
✓ Stream large files
✓ Use recursive: true for dirs
✓ Batch operations when possible
✓ Close handles properly

Security:
✓ Validate user input paths
✓ Use path.join for paths
✓ Set appropriate permissions
✓ Avoid path traversal attacks

The fs module provides comprehensive file system operations. Use the promises API for modern async code, streams for large files, and file handles for precise control. Always handle errors appropriately and clean up resources. For security, validate paths and set proper permissions.