How to Use createReadStream in Node.js for Reading Files

In Node.js, use fs.createReadStream(path, options) to read files as streams, which lets you process large files efficiently without loading them fully into memory. This method returns a readable stream that emits data chunks you can handle with events like data and end.

Syntax

The createReadStream method is called from the fs module and takes two main arguments:

• path: The file path to read from.
• options (optional): An object to customize the stream, such as encoding, start, and end positions.

It returns a readable stream that you can listen to for data events.

javascript

const fs = require('fs');

const stream = fs.createReadStream(path, options);

Example

This example shows how to read a text file using createReadStream and print its content chunk by chunk to the console.

javascript

const fs = require('fs');

const stream = fs.createReadStream('example.txt', { encoding: 'utf8' });

stream.on('data', (chunk) => {
  console.log('Received chunk:', chunk);
});

stream.on('end', () => {
  console.log('Finished reading file.');
});

stream.on('error', (err) => {
  console.error('Error reading file:', err.message);
});

Output

Received chunk: (first part of file content)
Received chunk: (next part of file content)
...
Finished reading file.

Common Pitfalls

Common mistakes when using createReadStream include:

• Not handling the error event, which can cause your program to crash if the file doesn't exist or is inaccessible.
• Forgetting to set the correct encoding, resulting in Buffer objects instead of strings.
• Assuming the entire file content is available at once; streams deliver data in chunks.

javascript

const fs = require('fs');

// Wrong: No error handling
const stream = fs.createReadStream('missing.txt');
stream.on('data', (chunk) => {
  console.log(chunk); // Buffer data
});

// Right: With error handling and encoding
const safeStream = fs.createReadStream('missing.txt', { encoding: 'utf8' });
safeStream.on('error', (err) => {
  console.error('File error:', err.message);
});
safeStream.on('data', (chunk) => {
  console.log(chunk); // String data
});

Quick Reference

Option	Description	Default
path	File path to read	Required
encoding	Character encoding (e.g., 'utf8')	null (returns Buffer)
start	Start byte position	0
end	End byte position	Infinity
highWaterMark	Buffer size in bytes for each chunk	64 * 1024 (64KB)

Key Takeaways

Use fs.createReadStream to read files efficiently as streams without loading entire files into memory.

Always handle the 'error' event to avoid crashes when files are missing or inaccessible.

Set the encoding option to get string data instead of Buffer objects.

Streams emit data in chunks, so process data inside 'data' event handlers.

You can specify start and end byte positions to read parts of a file.