Node.js fs/promises: async/await File System API

fs/promises is the promise-based version of Node's fs module. Its functions (readFile, writeFile, readdir, stat, mkdir, rm, rename and the rest) return a promise instead of taking a callback, so you await them and catch errors with try/catch. Import it with require('fs/promises') or import fs from 'fs/promises'.

import fs from 'fs/promises';

await fs.writeFile('todo.txt', 'write docs\n');
await fs.appendFile('todo.txt', 'ship it\n');

const text = await fs.readFile('todo.txt', 'utf8');
console.log(text.split('\n').filter(Boolean));

It prints [ 'write docs', 'ship it' ]: each await waits for one operation before the next line runs, so the append always happens after the first write. In an ES module await works at the top level; in CommonJS, wrap the code in an async function.

The functions you will use most

The names match the callback API, minus the callback. The readFile and writeFile pages cover those two in detail.

List a folder with readdir and stat

readdir returns names only. Call stat on each one to get its size or to tell files from folders, or pass { withFileTypes: true } to get entries that already know their type.

import fs from 'fs/promises';

// Setup: a folder with two files and a subfolder
await fs.mkdir('project/src', { recursive: true });
await fs.writeFile('project/README.md', '# Demo');
await fs.writeFile('project/notes.txt', 'abc');

const names = await fs.readdir('project');
console.log(names);

for (const name of names) {
    const info = await fs.stat('project/' + name);
    console.log(name, info.isDirectory() ? 'folder' : info.size + ' bytes');
}

const entries = await fs.readdir('project', { withFileTypes: true });
console.log(entries.filter((e) => e.isFile()).map((e) => e.name));

The loop prints README.md 6 bytes, notes.txt 3 bytes and src folder. stat rejects with ENOENT for a path that does not exist, which makes it a quick existence check when you also want the details.

Rename, move and delete

rename both renames and moves a file (within the same drive). rm deletes; it needs recursive: true for a folder that has contents, and force: true to not fail when the path is already gone.

import fs from 'fs/promises';

// Setup
await fs.mkdir('blog/drafts', { recursive: true });
await fs.writeFile('blog/drafts/post.md', 'hello');

await fs.mkdir('blog/published', { recursive: true });
await fs.rename('blog/drafts/post.md', 'blog/published/first-post.md');
console.log(await fs.readdir('blog/drafts'), await fs.readdir('blog/published'));

await fs.rm('blog/drafts', { recursive: true });
await fs.rm('blog/drafts', { recursive: true, force: true }); // already gone: no error
console.log(await fs.readdir('blog'));

The file moves from drafts to published under its new name, and after rm the blog folder lists only published. Remove force: true from the second rm and it rejects with ENOENT.

Handle errors with try/catch

A failed operation rejects its promise. With await, that rejection becomes an exception you catch like any other. The error's code tells you what went wrong.

import fs from 'fs/promises';

async function loadUsers() {
    try {
        const text = await fs.readFile('users.json', 'utf8');
        return JSON.parse(text);
    } catch (err) {
        if (err.code === 'ENOENT') return [];
        throw err;
    }
}

console.log(await loadUsers());

// Setup: create the file, then load again
await fs.writeFile('users.json', '[{"name":"Ada"}]');
console.log((await loadUsers())[0].name);

The first call finds no file and returns []; the second prints Ada. Codes to know: ENOENT (no such file), EEXIST (already exists), EISDIR (a folder where a file was expected), ENOTEMPTY (a folder still has contents) and EACCES (no permission).

A promise you do not await and do not .catch() becomes an unhandled rejection when it fails, and Node exits with an error. Await every call, or return its promise to a caller that does.

Read several files at once with Promise.all

A for loop with await reads files one after another. When the reads do not depend on each other, start them all and wait once with Promise.all: the disk works on them at the same time.

import fs from 'fs/promises';

// Setup: three small files
await fs.writeFile('a.txt', 'alpha');
await fs.writeFile('b.txt', 'beta');
await fs.writeFile('c.txt', 'gamma');

const files = ['a.txt', 'b.txt', 'c.txt'];
const contents = await Promise.all(files.map((f) => fs.readFile(f, 'utf8')));

console.log(contents);
console.log(contents.join('').length);

Promise.all keeps the order of the input array, so the result is [ 'alpha', 'beta', 'gamma' ] no matter which read finished first, and the joined length is 14. Rename 'b.txt' in the array to 'x.txt' and the whole await rejects with ENOENT.

If you need every result even when some reads fail, use Promise.allSettled; the promises page covers both.

Common mistakes

Mixing up the two modules. require('fs').readFile wants a callback; require('fs/promises').readFile returns a promise. Calling the callback version without a callback throws The "cb" argument must be of type function.

Forgetting await. const text = fs.readFile(...) is a pending promise, and text.split throws text.split is not a function.

Parallel writes to one file. Promise.all with several writes to the same path can leave mixed contents. Run those in sequence.