The ability to interact with the file system is a cornerstone of backend development. Whether you’re building a blog engine, managing user uploads, logging server activity, or scaffolding educational tutorials, file operations are everywhere. In Node.js, these tasks are handled by the built-in fs (File System) module—a robust and versatile API that allows developers to read, write, modify, and monitor files and directories with ease.
The fs module is part of Node.js core, meaning it requires no external installation and is available out of the box. It supports both synchronous and asynchronous methods, giving developers the flexibility to choose between blocking and non-blocking operations depending on their use case. For example, synchronous methods like fs.readFileSync() are useful in scripts or startup routines where performance isn’t critical, while asynchronous methods like fs.readFile() are ideal for scalable web servers that must remain responsive.
In recent versions of Node.js, the introduction of the Promise-based API via fs.promises has made file operations even more elegant. Developers can now use async/await syntax to write cleaner, more readable code without falling into callback hell. This modern approach is especially valuable in educational content, where clarity and structure are paramount.
The fs module covers a wide range of functionality. You can read and write files, append data, delete files, rename them, and even copy them—all with just a few lines of code. Directory management is equally straightforward: create folders with fs.mkdir(), list contents with fs.readdir(), and remove directories with fs.rmdir() or fs.rm() (for recursive deletion). These operations are essential for building dynamic applications that generate, organize, or clean up content on the fly.
Beyond basic file manipulation, the fs module also provides access to metadata through methods like fs.stat() and fs.lstat(). These allow you to inspect file size, creation date, permissions, and symbolic link status—useful for monitoring, auditing, or conditional logic based on file attributes. You can also use fs.access() to check whether a file exists or is readable/writable, which is particularly helpful in error handling and validation.
For performance-critical applications, Node.js offers stream-based file handling via fs.createReadStream() and fs.createWriteStream(). These methods allow you to process large files efficiently without loading them entirely into memory. Streams are ideal for building log parsers, media servers, or real-time data processors.
The fs module also supports file watching through fs.watch(), enabling developers to respond to changes in the file system—perfect for building live reload tools, monitoring systems, or automation scripts.
This reference guide is designed to provide a structured overview of the fs module, complete with method descriptions, usage patterns, and practical examples. Whether you’re scaffolding a tutorial, building a file manager, or teaching backend fundamentals, mastering the Node.js file system will empower you to create dynamic, responsive, and intelligent applications.
Here’s a comprehensive and practical Node.js File System Reference, tailored for backend developers, educators, and learners who want to master file operations using Node’s built-in fs module.
What Is the fs Module?
The fs (File System) module in Node.js provides an API for interacting with the file system. It supports both synchronous and asynchronous methods, and includes a modern Promise-based API via fs.promises. It’s essential for tasks like reading/writing files, managing directories, and handling file metadata.
Common File Operations
| Method | Description | API Style |
|---|---|---|
fs.readFile(path, callback) | Reads file content asynchronously | Callback |
fs.readFileSync(path) | Reads file content synchronously | Sync |
fs.promises.readFile(path) | Reads file content with Promises | Promise |
fs.writeFile(path, data, callback) | Writes data to a file | Callback |
fs.appendFile(path, data, callback) | Appends data to a file | Callback |
fs.unlink(path, callback) | Deletes a file | Callback |
fs.rename(oldPath, newPath, callback) | Renames a file | Callback |
fs.copyFile(src, dest, callback) | Copies a file | Callback |
Directory Operations
| Method | Description |
|---|---|
fs.mkdir(path, options, callback) | Creates a directory |
fs.rmdir(path, callback) | Removes a directory |
fs.readdir(path, callback) | Reads contents of a directory |
fs.promises.opendir(path) | Opens a directory stream (Promise-based) |
File Metadata & Permissions
| Method | Description |
|---|---|
fs.stat(path, callback) | Returns file/directory stats |
fs.lstat(path, callback) | Like stat, but for symbolic links |
fs.chmod(path, mode, callback) | Changes file permissions |
fs.access(path, mode, callback) | Checks file accessibility |
Streams & Performance
| Method | Description |
|---|---|
fs.createReadStream(path) | Reads large files efficiently |
fs.createWriteStream(path) | Writes data in chunks |
fs.watch(path, callback) | Watches for file changes |
Using streams is ideal for large files or real-time data processing, as it avoids loading entire files into memory.
Modern Promise-Based API
Node.js recommends using fs.promises for cleaner async/await syntax:
const fs = require('fs').promises;
async function readFileExample() {
try {
const data = await fs.readFile('example.txt', 'utf8');
console.log(data);
} catch (err) {
console.error('Error:', err);
}
}