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.
const bytes = new TextEncoder().encode('héllo'); const text = new TextDecoder().decode(bytes);
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
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'towindows-1252, sodecoder.encodingreports'windows-1252'. This differs slightly fromBuffer's'latin1'. encodeInto()never allocates and never writes a partial character, sowrittencan be less than the buffer length.- Streaming: pass
{ stream: true }for each chunk of a network or file stream, then calldecode()once more without it to flush. Splitting a multi-byte character across chunks otherwise corrupts it. For streams,TextDecoderStreamdoes 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 andBufferare all accepted as input todecode().
Related
atob()andbtoa(),Blob,structuredClone()- Lessons: Text encoding, Buffers