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().
import { readFile } from "node:fs/promises"; const text = await readFile("config.json", "utf8"); const config = JSON.parse(text);
Try it
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.
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
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, andJSON.parsethen fails. Strip it withtext.replace(/^\uFEFF/, ""). - Always pass an encoding for text. Calling
.toString()on aBufferworks but is easy to forget, and printing aBuffergives numbers, not text. - Invalid UTF-8 becomes
οΏ½. Decoding never throws. If you need to detect bad input, read the bytes and usenew 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.dirnamewhen you mean "next to this module". - Several awaits in a row are sequential. Use
Promise.allto 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 useimport data from "./file.json" with { type: "json" }.