Node.js File System

The Node.js fs (File System) module is one of the most essential tools in a backend developer's toolkit. It provides a robust API for interacting with the operating system's file system, allowing you to create, read, update, and delete files and directories. Since file I/O (Input/Output) can be resource-intensive, Node.js provides both Asynchronous (non-blocking) and Synchronous (blocking) versions of its methods to ensure your application remains performant.

Key Features of File System

1. Read/Write Files: Handle everything from simple .txt files to complex .json or binary image data.
2. Directory Manipulation: Manage your project structure by creating, removing, or scanning folders dynamically.
3. Asynchronous vs. Synchronous: Use non-blocking code for web servers to handle multiple requests, or synchronous code for simple CLI scripts where execution order is critical.
4. File Metadata: Inspect file properties like size, creation date, and permissions using fs.stat().

Common File System Methods

1. fs.readFile()

The fs.readFile() method reads a file without stopping the rest of your code from running. This is the standard way to retrieve data in Node.js applications.

const fs = require('fs');

fs.readFile('config.json', 'utf8', (err, data) => {
  if (err) {
    console.error("Failed to read file:", err.message);
    return;
  }
  console.log("File content received:");
  console.log(data);
});

Output:

{ "port": 3000, "db": "localhost" }

• The 'utf8' argument is crucial; without it, Node.js returns a Buffer (raw binary data) instead of a readable string.
• The callback function follows the "Error-First" pattern, a standard convention in Node.js.

2. fs.readFileSync()

This is the "Blocking" version of readFile. The script pauses at this line and won't move to the next line until the file is fully loaded into memory.

const fs = require('fs');

try {
  const data = fs.readFileSync('settings.txt', 'utf8');
  console.log(data);
} catch (err) {
  console.error("Error reading file:", err);
}

Output:

Application Settings: v1.0.4

• This is useful for loading configuration files during the startup phase of your application.

3. fs.writeFile()

Use fs.writeFile() to create a new file or completely overwrite an existing one. It’s perfect for saving user-generated content or exported reports.

const fs = require('fs');

const content = 'User: Jane Doe\nStatus: Active';

fs.writeFile('user_report.txt', content, (err) => {
  if (err) throw err;
  console.log('Report has been saved successfully!');
});

Output:

Report has been saved successfully!

4. fs.writeFileSync()

The synchronous counterpart to writeFile. It is often used in build scripts or initialization tasks where you need to ensure a file exists before moving to the next step.

const fs = require('fs');

fs.writeFileSync('temp.log', 'Temporary session started.');
console.log('Log initialized.');

5. fs.appendFile()

If you need to add data to a file without deleting what is already there such as adding a new entry to a log file use fs.appendFile().

const fs = require('fs');

const logEntry = `\nLog Entry: ${new Date().toISOString()}`;

fs.appendFile('server.log', logEntry, (err) => {
  if (err) throw err;
  console.log('New log entry added.');
});

• If the file does not exist, Node.js will automatically create it for you.

6. fs.unlink()

The term "unlink" is a bit of technical jargon for deleting a file. This method removes the link between the file name and the data on the hard drive.

const fs = require('fs');

fs.unlink('old_temp_file.txt', (err) => {
  if (err) {
    if (err.code === 'ENOENT') {
        console.log('File already deleted or does not exist.');
    } else {
        throw err;
    }
    return;
  }
  console.log('File deleted successfully.');
});

7. fs.rename()

While commonly used to change a file's name, this method can also move a file from one directory to another.

const fs = require('fs');

// Renaming a file
fs.rename('draft.txt', 'published.txt', (err) => {
  if (err) throw err;
  console.log('File status updated: Published.');
});

// Moving a file (real-world example)
// fs.rename('./uploads/image.jpg', './images/profiles/user_1.jpg', callback);

8. fs.mkdir()

Creates a new folder. By default, this will throw an error if the parent folder doesn't exist or if the folder already exists.

const fs = require('fs');

fs.mkdir('logs/daily', { recursive: true }, (err) => {
  if (err) throw err;
  console.log('Directory structure created.');
});

9. fs.readdir()

This method allows you to "scan" a directory. It returns an array containing the names of all the files and folders inside.

const fs = require('fs');

fs.readdir('./projects', (err, files) => {
  if (err) throw err;
  
  console.log(`Found ${files.length} items:`);
  files.forEach(file => {
      console.log(`- ${file}`);
  });
});

Output:

Found 3 items:
- website_alpha
- database_backup.sql
- notes.md

Summary

Mastering the fs module is a major milestone for any Node.js developer. It allows your applications to persist data, manage logs, and interact with the server's environment. While Synchronous methods are easy to write, always remember that Asynchronous methods are the key to building scalable, high-performance applications. For modern projects, you might also want to explore the fs/promises API, which allows you to use async/await syntax for even cleaner file handling code.