Read application assets
Load a small configuration or template file during asynchronous application startup.
Node.js · Function
readFile
fs.readFile() asynchronously reads an entire file into memory and reports completion through a callback. It returns text when an encoding is supplied; otherwise it returns a Buffer.
- Since
- v0.1.29
How it works
The callback-based fs.readFile() asynchronously reads the complete contents of a path into memory. Pass an encoding through options to receive a string; otherwise the result is a Buffer, and completion reports either an error or the data.
Syntax
fs.readFile(path[, options], callback)Parameters
| Name | Type | Description |
|---|---|---|
path | string | Buffer | URL | integer | The file path or a readable file descriptor. |
options | string | Object | Optional encoding or options object, including encoding and file flags. |
callback | function | Called after the operation completes with an error or the file data. |
Returns
The callback receives the file contents as a string when encoding is specified, otherwise as a Buffer; errors are passed as the first callback argument.
Key points
- Use it when an application needs the complete file contents through an asynchronous API.
- The implementation reads in chunks and lets the event loop turn between chunks.
- Its result type depends on whether an encoding is selected.
- An encoding option changes the result from raw binary data to decoded text.
- Handle the error first, then use data only after confirming the read succeeded.
Common mistakes
- Because the complete file is buffered, prefer a readable stream for large files to reduce memory usage.
- Do not rely on consistent directory behavior across operating systems; use directory-specific APIs when appropriate.
- If path is a file descriptor, it must be opened with read access.
Example: Read a text file asynchronously
import { readFile } from 'node:fs/promises';
const text = await readFile(new URL('./config.json', import.meta.url), 'utf8');
console.log(text);Reads config.json asynchronously as UTF-8 text and prints its contents.
When to use it
Consume whole-file data
Retrieve a complete text or binary file when incremental processing is unnecessary.
Process uploaded files
Read user-provided files after validating the path and handling filesystem errors.
Interview questions
QWhat does fs.readFile() do and what does its callback receive?
fs.readFile(path[, options], callback) performs an asynchronous full-file read. The callback receives an error and the resulting string or Buffer.
Follow-up: How would you handle a very large file? Use fs.createReadStream() so data can be processed incrementally instead of being fully buffered.
QHow does the encoding option affect the return value?
Without an encoding, the returned data is a Buffer. Supplying an encoding, such as 'utf8', makes the result a string.
Follow-up: What happens when options is a string? It is treated as the encoding value.
QIs fs.readFile() non-blocking and memory-efficient for large files?
The method yields control between chunks while reading, so it does not synchronously block JavaScript execution. It still stores the entire file in memory before completion.
Follow-up: When is fs.readFileSync() preferable? Only when synchronous behavior is intentionally required, since it blocks the event loop.
Related
fs.readFileSyncfsPromises.readFilefs.createReadStreamfs.open