Node.js · Module

fs

The node:fs module provides Node.js access to files and directories through synchronous, callback-based, and promise-based APIs. It is suited to reading, writing, opening, inspecting, and streaming filesystem data.

How it works

The node:fs module provides filesystem access through callback, synchronous, and promise-based APIs. Import the promise variant when asynchronous operations should be composed with await; common operations accept paths and optional encoding or options, while reads return data and writes complete after the file has been updated.

Syntax

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

Key points

node:fs exposes filesystem operations modeled after POSIX behavior.
Most filesystem work can be expressed as blocking synchronous calls, callbacks, or promises.
Use node:fs/promises when you want promise-returning operations.
Use node:fs for callback-oriented and synchronous filesystem APIs.
Synchronous filesystem calls block the event loop, so they should be reserved for suitable contexts.

Example: Copy transformed file contents

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

const input = await readFile('input.txt', 'utf8');
await writeFile('output.txt', input.toUpperCase());
console.log('Wrote output.txt');

Reads a UTF-8 text file and writes an uppercase copy using promise-based filesystem APIs.

When to use it

Read files

Read configuration, templates, or other small files during asynchronous application work.

Write files

Persist generated content, logs, or application state.

Stream file data

Process large files incrementally without loading them fully into memory.

Manage filesystem resources

Inspect paths, permissions, metadata, and directory contents.

node:fs/promises
fs.readFile
fs.writeFile
fs.open
fs.access
fs.createReadStream
fs.createWriteStream

Source: File system | Node.js v26.4.0 Documentation. Checked 2026-10-15.

fs