Node.js fs.readFile: Read Files (Sync, Async, Promises)

fs.readFile(path, 'utf8', callback) reads a whole file and passes its contents to the callback as a string. fs.readFileSync(path, 'utf8') returns the string directly and waits for the read to finish, and await readFile(path, 'utf8') from fs/promises does the same without blocking. Leave out 'utf8' and you get a Buffer of raw bytes instead of text.

const fs = require('fs');

// Setup: create a file to read
fs.writeFileSync('notes.txt', 'Buy milk\nCall Ada');

fs.readFile('notes.txt', 'utf8', (err, text) => {
    if (err) {
        console.error('Could not read:', err.message);
        return;
    }
    console.log(text);
});

console.log('readFile called');

readFile called prints first: readFile only starts the read, and the callback runs once the contents are ready. Delete 'utf8', and run it again: the callback gets <Buffer 42 75 79 20 6d 69 6c 6b 0a 43 61 6c 6c 20 41 64 61>, the raw bytes of the file.

readFile vs readFileSync vs fs/promises

All three read the same file. They differ in how you get the result and whether the rest of the program waits.

const fs = require('fs');
const fsp = require('fs/promises');

// Setup: create a file to read
fs.writeFileSync('greeting.txt', 'Hello from a file');

// 1. Sync: returns the text, blocks until done
const a = fs.readFileSync('greeting.txt', 'utf8');
console.log('sync:', a);

// 2. Callback: the result arrives later
fs.readFile('greeting.txt', 'utf8', (err, b) => {
    console.log('callback:', b);
});

// 3. Promise: await it inside an async function
async function main() {
    const c = await fsp.readFile('greeting.txt', 'utf8');
    console.log('promise:', c);
}
main();

The sync line prints first because nothing else runs until it returns. The other two finish after the main code, in whichever order their reads complete.

Use readFileSync when reading a config at startup or in a short script. In a server, a sync read stops every other request while the disk works, so use the promise version there. The fs/promises page covers the rest of that API.

Handle a missing file (ENOENT)

When the file does not exist, the error has code: 'ENOENT' ("error, no entry"). Check err.code to tell a missing file apart from other failures, like a permission problem.

const fs = require('fs');

function readSettings(file) {
    try {
        return fs.readFileSync(file, 'utf8');
    } catch (err) {
        if (err.code === 'ENOENT') {
            return 'default settings';
        }
        throw err; // anything else is a real problem
    }
}

console.log(readSettings('settings.txt'));

// Setup: now create the file and read again
fs.writeFileSync('settings.txt', 'dark mode');
console.log(readSettings('settings.txt'));

The first call finds no file and falls back to default settings; the second reads dark mode. Rethrowing the other errors keeps real problems visible instead of quietly using defaults.

fs.existsSync: why to just try the read

fs.existsSync(path) returns true or false, and it is tempting to check before reading:

if (fs.existsSync('data.txt')) {
    const text = fs.readFileSync('data.txt', 'utf8');
}

That is two steps where one is enough, and the file can be deleted between them, so the read can still throw. Try the read and handle ENOENT, as above. existsSync is fine when you only need to know whether something exists and will not open it, for example to decide whether to create a folder.

Read a JSON file

Read the text, then parse it with JSON.parse. A file with a syntax error throws a SyntaxError, so keep it inside the same try.

const fs = require('fs');

// Setup: write a JSON file
fs.writeFileSync('config.json', '{ "port": 3000, "debug": true }');

const config = JSON.parse(fs.readFileSync('config.json', 'utf8'));
console.log(config.port + 1);
console.log(typeof config.debug);

It prints 3001 and boolean: after parsing, the values have their JSON types. require('./config.json') also works, but it caches the result, so a second require returns the old object even after the file changes.

Read a file line by line

For a file that fits in memory, read it whole and split on the newline character. Filter out the empty string that a final newline leaves behind.

const fs = require('fs');

// Setup: write a file with three lines
fs.writeFileSync('log.txt', 'start\nwarn: disk 91%\nstop\n');

const lines = fs.readFileSync('log.txt', 'utf8').split('\n');
console.log(lines.length);

lines.filter(Boolean).forEach((line, i) => {
    console.log(i + 1, line);
});

The split gives 4 items, the last one empty, so the loop prints three numbered lines. Files written on Windows end lines with \r\n; split on /\r?\n/ to handle both.

A log of several gigabytes does not fit in memory. Stream it instead, so only one line at a time is held:

const fs = require('fs');
const readline = require('readline');

async function main() {
    const rl = readline.createInterface({
        input: fs.createReadStream('big.log'),
        crlfDelay: Infinity,
    });
    for await (const line of rl) {
        console.log(line);
    }
}
main();

Common mistakes

Using the result outside the callback. const text = fs.readFile(...) is undefined. The contents exist only inside the callback, or after await.

Forgetting the encoding. Without 'utf8' you get a Buffer, and data.split('\n') throws data.split is not a function. Pass the encoding whenever you want text.

Paths relative to the wrong folder. 'data.txt' is looked up where node was started. Use path.join(__dirname, 'data.txt') for a file that ships next to your script.