Skip to content
Tutorials Center
My learning

Topics

Node.js Reference ยท fs and fs/promises

Node.js fs.readFileSync() method

Reference for fs.readFileSync() in Node.js: read a file as a Buffer or string, encodings and flags, error handling with try/catch, and when blocking is acceptable.

fs.readFileSync() reads a whole file and returns its contents directly. The call blocks the thread until the read is finished, so nothing else in your program runs meanwhile. In exchange there are no callbacks or promises: you get a value, or an exception.

That makes it a good fit for start-up work (loading configuration, templates, keys), command-line scripts and tests. In a server's request path, use fs.readFile() instead so one slow disk read does not stall every client.

NODE
import { readFileSync } from 'node:fs';

const text = readFileSync('settings.json', 'utf8');

Try it

Node.js Text, bytes and JSON

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Node.js Handling missing files

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Syntax

NODE
fs.readFileSync(path, options?): Buffer | string

// path:    string | Buffer | URL | integer (file descriptor)
// options: string (encoding) | { encoding?: string | null, flag?: string }
Name Description
path File name, file: URL or an open file descriptor.
options.encoding Encoding for the returned string ('utf8', 'latin1', 'hex', 'base64', ...). Default null returns a Buffer.
options.flag Open flag, default 'r'.

Returns: a Buffer, or a string if an encoding was given.

Errors: throws synchronously. Common codes: ENOENT, EISDIR, EACCES, EMFILE. The error object has code, syscall, path and errno.

Usage notes

  • Blocking. Every other timer, request and callback waits. Use it in code that runs once, never per request in a server.
  • Wrap in try/catch. There is no error argument; failures are exceptions. Catch the specific code you expect and rethrow the rest, as in readOptional() above.
  • No encoding means bytes. Pass 'utf8' for text. A default Buffer printed with console.log shows hex pairs, not characters.
  • JSON shortcut. JSON.parse(readFileSync(file, 'utf8')) is the classic way to load a JSON file in CommonJS or ES modules; require('./file.json') caches the result, while this reads fresh each time.
  • Relative paths resolve against process.cwd(). For files shipped next to your code, join with import.meta.dirname or __dirname.
  • Reading from 0 or '/dev/stdin' returns whatever is piped in, as a convenient way to slurp standard input in small scripts. It fails with EAGAIN on some terminals, so prefer streams for interactive input.
  • Byte order mark. A UTF-8 BOM is returned as ๏ปฟ; strip it before parsing JSON.
  • Large files. The whole content is held in memory and files over 2 GiB fail with ERR_FS_FILE_TOO_LARGE. Stream them.