Node.js Buffers for Binary Data

Node.js Buffers are used to work with raw binary data in Node.js. A Buffer represents a fixed-size sequence of bytes. Buffers are commonly used while reading files, writing files, handling TCP streams, processing request bodies, working with images, and converting data between formats such as UTF-8, hexadecimal, and Base64.

Node.js provides the Buffer class so JavaScript programs can handle binary data directly. A string stores characters, but a buffer stores bytes. This difference matters when you are dealing with files, network packets, compressed data, encryption output, or any data where each byte has to be preserved exactly.

Raw memory allocated to buffers is outside the Node.js V8 heap memory. In modern Node.js, Buffer also works with the Uint8Array model, so many byte-level operations look similar to typed array operations.

In this tutorial, we shall learn how to

You will also learn when to use Buffer.alloc(), Buffer.allocUnsafe(), Buffer.from(), buf.write(), buf.toString(), and buf.values(). For the complete API surface, refer to the official Node.js Buffer documentation.

When Node.js Buffer is used in real programs

Node.js Buffer is useful whenever data is not naturally handled as a plain JavaScript string. The most common cases are file system operations, network communication, binary protocols, cryptography, compression, and encoding conversion.

  • File system: fs.readFile() can return file content as a Buffer when no character encoding is specified.
  • Network streams: TCP sockets and HTTP streams may deliver chunks of data as Buffer objects.
  • Encoding conversion: Buffers can convert text to and from formats such as utf8, hex, and base64.
  • Binary data handling: Images, archives, encrypted values, and protocol messages can be represented as byte sequences.

Node.js Buffer Creation Methods

There are quite multiple ways to create buffer in Node.js. We shall go through each of them one by one.

Buffer of specified length with Buffer.allocUnsafe()

To create a buffer of specified length, use Buffer.allocUnsafe(int) method as shown in the following.

</>
Copy
Buffer.allocUnsafe(bufferLength);

Example

</>
Copy
const buf1 = Buffer.allocUnsafe(10);

bufferLength is an integer specifying the length of buffer to be created.

The buffer created is not initialized, which means it can contain garbage values. You may overwrite the garbage values using fill() or write() methods.

Use Buffer.allocUnsafe() only when you are going to overwrite every byte before reading from the buffer. It can be faster than zero-filled allocation, but the existing memory content should never be treated as valid application data.

Zero-filled Buffer with Buffer.alloc()

To create a Zero filled buffer of specified length, use Buffer.alloc(int) method as shown in the following.

</>
Copy
Buffer.alloc(bufferLength);

Example

</>
Copy
const buf1 = Buffer.alloc(10);

bufferLength is an integer specifying the length of buffer to be created. The buffer contains all memory locations filled with zeroes.

Buffer.alloc() is slower than Buffer.allocUnsafe().

For most beginner examples and application code where safety is preferred, Buffer.alloc() is the clearer choice because the bytes are initialized to 0.

Buffer filled with a specified value

To create a buffer of specified length and filled with a specified value, use Buffer.alloc(int, int) method as shown in the following.

</>
Copy
Buffer.alloc(bufferLength, value);

Example

const buf1 = Buffer.allocUnsafe(10, 3);

bufferLength is an integer specifying the length of buffer to be created. The buffer contains all memory locations filled with value.

When you want a buffer initialized with a specific fill value, use Buffer.alloc(size, fill). This makes the intention clear and avoids reading from uninitialized memory.

</>
Copy
const filledBuffer = Buffer.alloc(10, 3);

console.log(filledBuffer);
<Buffer 03 03 03 03 03 03 03 03 03 03>

Create Buffer from a string with Buffer.from()

Buffer.from() is commonly used when you already have data and want to convert it into bytes. The following example creates a buffer from a UTF-8 string.

</>
Copy
const messageBuffer = Buffer.from('Hello Node.js', 'utf8');

console.log(messageBuffer);
console.log(messageBuffer.toString('utf8'));
<Buffer 48 65 6c 6c 6f 20 4e 6f 64 65 2e 6a 73>
Hello Node.js

The second argument is the encoding. If you do not provide it, Node.js uses utf8 for strings.

Create Buffer from an array of bytes

You can create a Buffer from an array of byte values. Each value should be in the byte range 0 to 255.

</>
Copy
const bytes = Buffer.from([65, 66, 67, 68]);

console.log(bytes);
console.log(bytes.toString('utf8'));
<Buffer 41 42 43 44>
ABCD

Buffer.alloc(), Buffer.allocUnsafe(), and Buffer.from() comparison

MethodWhat it doesBest use
Buffer.alloc(size)Creates a buffer and fills it with zeroesSafe default when you need an empty buffer
Buffer.alloc(size, fill)Creates a buffer and fills it with the specified valueWhen every byte should start with a known value
Buffer.allocUnsafe(size)Creates an uninitialized bufferPerformance-sensitive code that overwrites every byte before reading
Buffer.from(value)Creates a buffer from existing dataStrings, arrays, ArrayBuffer values, and existing buffers

Node.js Buffer Write Methods

There are many methods of Buffer class to write data of different formats to a buffer. In this section, we shall learn to write a string to buffer.

To write string a buffer, use Buffer.write method, as shown in the following.

</>
Copy
Buffer.write(string[, offset[, length]][, encoding]);

In practical code, write() is called on a buffer instance. The common form is shown below.

</>
Copy
buffer.write(string[, offset[, length]][, encoding]);

Example

const buf1 = Buffer.allocUnsafe(100);
const len = buf1.write('welcomeuser',2,5,'utf8');
  • string starting from the offset, number of characters provided by length are written to the buffer in the encoding format specified.
  • write() method returns the number of bytes written to the buffer.

The offset argument tells Node.js where writing should begin inside the buffer. The length argument limits how many bytes can be written. For UTF-8 text, remember that the number of bytes may differ from the number of characters for non-ASCII characters.

</>
Copy
const buf = Buffer.alloc(12);

const bytesWritten = buf.write('Node.js', 0, 'utf8');

console.log(bytesWritten);
console.log(buf.toString('utf8', 0, bytesWritten));
7
Node.js

Write numbers to a Node.js Buffer

Buffers can also store numeric values using methods such as writeUInt8(), writeInt16BE(), writeInt16LE(), writeUInt32BE(), and writeUInt32LE(). The suffix BE means big-endian byte order, and LE means little-endian byte order.

</>
Copy
const packet = Buffer.alloc(4);

packet.writeUInt16BE(258, 0);
packet.writeUInt16BE(772, 2);

console.log(packet);
<Buffer 01 02 03 04>

Numeric read and write methods are useful when implementing binary file formats or network protocols where each byte position has a defined meaning.

Node.js Buffer Read Methods

To read bytes from a buffer, use Buffer.values method as shown in the following.

</>
Copy
Buffer.values();

Creates and returns an iterator for buf1 values (bytes). This function is called automatically when a Buffer is used in a for..of statement.

read-buffer.js

</>
Copy
  const buf1 = Buffer.allocUnsafe(11);

  const len = buf1.write('welcomeuser');

  for(const byt of buf1.values()){
    console.log(byt);
  }

Output

$ node read-buffer.js 
119
101
108
99
111
109
101
117
115
101
114

Each printed number is the decimal byte value stored in the buffer. For example, the character w is represented by byte value 119 in UTF-8.

Read Buffer content as a string with buf.toString()

When the buffer contains text, buf.toString() is usually the easiest way to read it back. You can specify the encoding and optional start and end positions.

</>
Copy
const buf = Buffer.from('welcomeuser', 'utf8');

console.log(buf.toString());
console.log(buf.toString('utf8', 0, 7));
welcomeuser
welcome

Read individual bytes from a Buffer

You can read a byte by index because a Buffer behaves like an array of bytes. Index positions start at 0.

</>
Copy
const buf = Buffer.from('ABC');

console.log(buf[0]);
console.log(buf[1]);
console.log(buf[2]);
65
66
67

Read numeric values from a Node.js Buffer

If a buffer stores binary numbers, use methods such as readUInt8(), readUInt16BE(), readUInt16LE(), readInt32BE(), and readInt32LE(). Use the same byte order that was used while writing the value.

</>
Copy
const buf = Buffer.from([0x01, 0x02, 0x03, 0x04]);

console.log(buf.readUInt16BE(0));
console.log(buf.readUInt16BE(2));
258
772

Node.js Buffer encodings: utf8, hex, and base64

A Buffer stores bytes, but you can display or create those bytes using different encodings. The common encodings are utf8 for text, hex for hexadecimal representation, and base64 for compact text representation of binary data.

</>
Copy
const buf = Buffer.from('Node.js Buffer', 'utf8');

console.log(buf.toString('utf8'));
console.log(buf.toString('hex'));
console.log(buf.toString('base64'));
Node.js Buffer
4e6f64652e6a7320427566666572
Tm9kZS5qcyBCdWZmZXI=

Use the same encoding when converting back from an encoded string. For example, a string produced with toString('base64') should be passed to Buffer.from(value, 'base64') when decoding it.

</>
Copy
const encoded = 'Tm9kZS5qcyBCdWZmZXI=';
const decoded = Buffer.from(encoded, 'base64');

console.log(decoded.toString('utf8'));
Node.js Buffer

Buffer.byteLength() and string length are not always same

JavaScript string length counts characters or code units, but Buffer.byteLength() returns how many bytes are required for a string in a given encoding. This is important when allocating a buffer for text that may contain non-ASCII characters.

</>
Copy
const text = 'नमस्ते';

console.log(text.length);
console.log(Buffer.byteLength(text, 'utf8'));
6
18

The byte length can be greater than the visible character count because UTF-8 may use multiple bytes for a single character.

Node.js Buffers with fs.readFile()

When a file is read without specifying an encoding, Node.js returns a Buffer. If you specify an encoding such as utf8, Node.js returns a string instead.

</>
Copy
const fs = require('node:fs');

const data = fs.readFileSync('sample.txt');

console.log(Buffer.isBuffer(data));
console.log(data.toString('utf8'));

This pattern is useful when you need exact bytes from a file. Convert to a string only when you know the file contains text in the expected encoding.

Common mistakes while using Node.js Buffers

  • Reading before writing: Do not read from a buffer created with Buffer.allocUnsafe() until you have overwritten the required bytes.
  • Confusing bytes and characters: Use Buffer.byteLength() when allocating space for encoded text.
  • Using the wrong encoding: The encoding used to decode data must match the encoding used to create or receive it.
  • Ignoring offsets: When using write(), toString(), or numeric read methods, check start positions and lengths carefully.
  • Mixing endian formats: If data is written using a big-endian method, read it using the matching big-endian method.

Node.js Buffer QA checklist for examples

  • The tutorial explains that Buffer stores bytes, not ordinary JavaScript characters.
  • The examples use Buffer.alloc() for safe initialized buffers and explain when Buffer.allocUnsafe() is acceptable.
  • The write examples show the number of bytes written and avoid reading uninitialized bytes.
  • The read examples include both byte iteration and string conversion with toString().
  • The encoding examples show at least one conversion using utf8, hex, or base64.
  • The examples use PrismJS language classes for new JavaScript and output code blocks.

FAQs on Node.js Buffers

What is a Buffer in Node.js?

A Buffer in Node.js is an object used to store and work with raw binary data. It represents a fixed-length sequence of bytes and is commonly used with files, streams, network data, and encoding conversion.

What is the difference between Buffer.alloc() and Buffer.allocUnsafe()?

Buffer.alloc() creates a buffer with initialized bytes, usually filled with zeroes. Buffer.allocUnsafe() creates an uninitialized buffer and may contain old memory values, so it should be used only when all bytes will be overwritten before reading.

How do I convert a Node.js Buffer to a string?

Use buf.toString(encoding). For normal text, buf.toString('utf8') is commonly used. You can also pass start and end positions to convert only a part of the buffer.

When does fs.readFile() return a Buffer?

fs.readFile() and fs.readFileSync() return a Buffer when no encoding is specified. If you pass an encoding such as utf8, the file content is returned as a string.

How can I create a Buffer from Base64 in Node.js?

Use Buffer.from(base64String, 'base64') to decode a Base64 string into bytes. Then use toString('utf8') only if the decoded bytes represent UTF-8 text.

Node.js Buffer examples summary

In this Node.js Tutorial – Node.js Buffers, we have learnt to create, write to and read Buffers in Node.js. In our next tutorials, we shall learn some interesting operations with Buffers.

Use Buffer.from() when creating bytes from existing data, Buffer.alloc() when you need a safe initialized buffer, and Buffer.allocUnsafe() only when you will overwrite the memory before reading it. Use buf.write(), buf.toString(), byte indexes, and numeric read/write methods depending on whether the buffer contains text, raw bytes, or binary numbers.