Skip to content
Tutorials Center
My learning

Topics

Node.js Reference · Globals and Console

TextEncoder and TextDecoder

Reference for TextEncoder and TextDecoder in Node.js: convert strings to UTF-8 bytes, decode bytes with other encodings, fatal mode, BOM handling and streaming.

TextEncoder turns a JavaScript string into UTF-8 bytes (a Uint8Array). TextDecoder does the reverse and can read several encodings, such as UTF-8, UTF-16 and Latin-1. Both are web-standard classes and are available as globals in Node.js.

They are the portable way to move between text and bytes: the same code works in browsers, Deno, Bun and Node.js. In Node-only code, Buffer.from(text) and buffer.toString() do the same job.

NODE
const bytes = new TextEncoder().encode('héllo');
const text = new TextDecoder().decode(bytes);

Try it

Node.js Encoding and decoding

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 Invalid data, BOM and streaming

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
new TextEncoder()
encoder.encode(input?: string): Uint8Array
encoder.encodeInto(source: string, destination: Uint8Array): { read, written }
encoder.encoding   // always 'utf-8'

new TextDecoder(label?: string, options?: { fatal?: boolean, ignoreBOM?: boolean })
decoder.decode(input?: BufferSource, options?: { stream?: boolean }): string
decoder.encoding, decoder.fatal, decoder.ignoreBOM
Name Description
label Encoding name such as 'utf-8' (default), 'utf-16le', 'latin1'. Labels are case-insensitive and normalized.
fatal If true, invalid input throws instead of producing U+FFFD.
ignoreBOM If true, a leading byte order mark is kept in the output instead of being removed.
stream If true, an incomplete character at the end is held back for the next call.

Returns: a Uint8Array from encode(); an object with read (UTF-16 code units consumed) and written (bytes) from encodeInto(); a string from decode().

Errors: an unknown label throws a RangeError (ERR_ENCODING_NOT_SUPPORTED); with fatal: true, bad bytes throw a TypeError with code ERR_ENCODING_INVALID_ENCODED_DATA.

Usage notes

  • The encoder is UTF-8 only. To produce UTF-16 or Latin-1 bytes, use Buffer.from(text, 'utf16le') or build the bytes yourself.
  • Lone surrogates in the input string are replaced with U+FFFD (the replacement character) when encoding.
  • Latin-1 label: the web standard maps 'latin1' to windows-1252, so decoder.encoding reports 'windows-1252'. This differs slightly from Buffer's 'latin1'.
  • encodeInto() never allocates and never writes a partial character, so written can be less than the buffer length.
  • Streaming: pass { stream: true } for each chunk of a network or file stream, then call decode() once more without it to flush. Splitting a multi-byte character across chunks otherwise corrupts it. For streams, TextDecoderStream does this for you.
  • Default BOM behavior: the BOM is stripped from the output, which surprises people who expect  at the start of a file.
  • Reuse instances: creating one decoder and calling it many times is cheaper than creating one per call.
  • ArrayBuffer, typed arrays and Buffer are all accepted as input to decode().