fs/promises module

The fs/promises module provides promise‑based versions of all the standard fs functions. Introduced in Node.js 10, it allows you to work with the file system using async/await syntax, avoiding callback nesting and making error handling more straightforward.

Syntax

const fs = require('fs').promises;           // CommonJS
import fs from 'fs/promises';                // ES modules
import { readFile, writeFile } from 'fs/promises'; // named imports

Parameters

Most fs/promises functions share the same parameters as their callback‑based counterparts, minus the callback.

Parameter	Type	Default	Description
path	string	(required)	File or directory path. Can be absolute or relative.
options	object or string	null	Encoding (e.g., 'utf8') or an object with encoding, flag, mode, etc.
data	string, Buffer, or Uint8Array	(required for writes)	Content to write to the file.

Examples

Reading a file with async/await

import { readFile } from 'fs/promises';

async function readConfig() {
  try {
    const data = await readFile('config.json', 'utf8');
    console.log('Config loaded:', JSON.parse(data));
  } catch (err) {
    console.error('Failed to read config:', err.message);
  }
}

readConfig();

Output (assuming config.json contains {"port": 3000}):

Config loaded: { port: 3000 }

Writing a file with promises

const fs = require('fs').promises;

fs.writeFile('log.txt', `Accessed at ${new Date().toISOString()}\n`, { flag: 'a' })
  .then(() => console.log('Log appended'))
  .catch(err => console.error('Write failed:', err));

Output:

Log appended

Creating a directory recursively

import { mkdir } from 'fs/promises';

async function setupProject() {
  await mkdir('./project/src/utils', { recursive: true });
  console.log('Directory structure created');
}

setupProject();

Output:

Directory structure created

Common Patterns

Parallel file operations with Promise.all

import { readFile } from 'fs/promises';

async function readMultipleFiles(filePaths) {
  const promises = filePaths.map(path => readFile(path, 'utf8'));
  const contents = await Promise.all(promises);
  return contents; // array of file contents in same order
}

// Usage
readMultipleFiles(['a.txt', 'b.txt', 'c.txt'])
  .then(results => console.log('Files read:', results))
  .catch(err => console.error('One or more files failed:', err));

Error handling in promise‑based fs

Because fs/promises functions return promises, you can use standard promise‑catching patterns:

import { unlink } from 'fs/promises';

async function safeDelete(path) {
  try {
    await unlink(path);
    console.log(`Deleted ${path}`);
  } catch (err) {
    if (err.code === 'ENOENT') {
      console.warn(`File ${path} did not exist, skipping`);
    } else {
      throw err; // re‑throw unexpected errors
    }
  }
}

See Also

• Fs:: – Callback‑based file system API
• Stream:: – Stream‑based file processing