Skip to content
Tutorials Center
My learning

Topics

Node.js Reference Β· fs and fs/promises

Node.js fsPromises.readFile() method

Reference for fsPromises.readFile() in Node.js: read a whole file as a Buffer or string with await, the encoding, flag and signal options, and error handling.

fsPromises.readFile(path[, options]) reads an entire file and returns a promise for its contents. Without an encoding the promise resolves with a Buffer holding the raw bytes. With an encoding such as "utf8" you get a string. It is the shortest way to load a config file, a template or a small data file in code that already uses async and await.

Import it as import { readFile } from "node:fs/promises" or import fs from "node:fs/promises". The whole file is held in memory, so for very large files use fs.createReadStream() or a FileHandle and read in pieces. The callback and sync versions are fs.readFile() and fs.readFileSync().

NODE
import { readFile } from "node:fs/promises";

const text = await readFile("config.json", "utf8");
const config = JSON.parse(text);

Try it

Node.js Buffer, string 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 Errors and cancellation

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
fsPromises.readFile(path[, options]): Promise<Buffer | string>
Name Description
path A string, Buffer, URL or a FileHandle. With a FileHandle, reading starts at its current position and the handle is not closed.
options An encoding string, or an object.
options.encoding "utf8", "base64", "hex", "latin1" and other Buffer encodings. Default null (returns a Buffer).
options.flag A file system flag. Default "r".
options.signal An AbortSignal to cancel an in-progress read.

Returns: a promise for a Buffer, or a string when an encoding is given.

Errors: ENOENT (missing), EISDIR (path is a directory), EACCES (no permission), ERR_FS_FILE_TOO_LARGE (over 2 GiB, the Buffer limit), and an AbortError (err.code === "ABORT_ERR") when the signal fires.

Usage notes

  • UTF-8 BOM is not removed. A file saved with a byte order mark yields a string that starts with \uFEFF, and JSON.parse then fails. Strip it with text.replace(/^\uFEFF/, "").
  • Always pass an encoding for text. Calling .toString() on a Buffer works but is easy to forget, and printing a Buffer gives numbers, not text.
  • Invalid UTF-8 becomes οΏ½. Decoding never throws. If you need to detect bad input, read the bytes and use new TextDecoder("utf-8", { fatal: true }).
  • Size limit. Strings and buffers cannot be larger than about 2 GiB (Buffers) or about 512 million characters (strings, engine-dependent). Stream anything big.
  • Relative paths use the process working directory, not the file doing the reading. Build paths from import.meta.dirname when you mean "next to this module".
  • Several awaits in a row are sequential. Use Promise.all to read independent files at the same time, but keep an eye on the open-file limit when the list is long (thousands of files).
  • It reads the file as it is at that moment. A file being appended to by another process may be read half-complete.
  • JSON files: no extra import is needed for plain reading; JSON.parse(await readFile(...)) is the idiom. For static config you can also use import data from "./file.json" with { type: "json" }.