iconv-lite - Character Encoding Conversion

Common errors

• TypeError: iconv-lite does not support the encoding: foo-bar-encoding

  cause Attempting to encode or decode with an unsupported or misspelled character encoding name.
  fix Use `iconv.encodingExists('encodingName')` to verify support. Refer to `iconv-lite` documentation or source for a list of supported encodings. Common errors include 'UTF8' instead of 'utf8'.

• TS2307: Cannot find module 'iconv-lite' or its corresponding type declarations.

  cause TypeScript compiler cannot locate the package or its type definitions. This can happen if the package is not installed, or if TypeScript configuration is incorrect.
  fix Ensure the package is installed (`npm install iconv-lite`) and your `tsconfig.json` includes `node_modules/@types` or has `typeRoots` correctly configured. If using an older version that didn't ship types, install `@types/iconv-lite`.

• TS2305: Module ''iconv-lite'' has no default export.

  cause Attempting to `import iconv from 'iconv-lite'` when using CommonJS with TypeScript prior to v0.7.2, or an incorrect import style for the target module system.
  fix For CommonJS in TypeScript (prior to v0.7.2), use `import * as iconv from 'iconv-lite'` or `const iconv = require('iconv-lite')`. For ESM, `import iconv from 'iconv-lite'` is correct. Ensure your `tsconfig.json`'s `module` and `esModuleInterop` settings are appropriate for your environment.

Warnings

• breaking Version `1.0.0-alpha.1` and later remove support for Node.js versions older than 18. Users on older Node.js runtimes must remain on `iconv-lite@0.x` or upgrade their Node.js environment.
  Fix: Upgrade your Node.js runtime to version 18 or higher, or pin `iconv-lite` to a `0.x` version using `npm install iconv-lite@0.x`.
• breaking The `safe-buffer` dependency has been removed in `v1.0.0-alpha.1` as native Buffer methods are now used. This may cause issues if your environment relied on `safe-buffer` polyfills for older Node.js versions (which are no longer supported anyway).
  Fix: Ensure your Node.js environment is v18+ where native Buffer methods are robust and `safe-buffer` is not needed. No direct code fix is typically required unless you had custom Buffer polyfills.
• breaking `v1.0.0-alpha.1` switches to using native `TextDecoder` for decoding where possible. While this generally improves performance and compliance, it might introduce subtle differences in edge-case decoding behavior compared to the previous pure-JS implementation.
  Fix: Thoroughly test decoding functionality if upgrading to `v1.x` and relying on specific, potentially non-standard decoding behaviors in `v0.x`.
• gotcha Prior to `v0.7.2`, TypeScript definitions for CommonJS exports had issues, leading to incorrect type errors or difficulties in consuming the library correctly in TypeScript projects using `require()`.
  Fix: Upgrade to `iconv-lite@0.7.2` or newer to get corrected TypeScript definitions for CommonJS exports. If stuck on an older version, manual type declarations (`declare module 'iconv-lite'`) might be necessary.
• gotcha Older versions of `iconv-lite` (prior to `v0.7.0`) had issues handling split surrogate pairs when streaming UTF-8 encoding. This could lead to incorrect output if a high and low surrogate character were separated across different chunks of data.
  Fix: Upgrade to `iconv-lite@0.7.0` or newer to ensure correct handling of split surrogate pairs during UTF-8 streaming encoding. This is especially important for chunked data processing.

Install

• npm install iconv-lite npm
• yarn add iconv-lite yarn
• pnpm add iconv-lite pnpm

Imports

• iconv
  wrong:

  import { iconv } from 'iconv-lite'

  correct:

  import iconv from 'iconv-lite'

  The primary `iconv` object is a default export for ESM. In CommonJS, you'd `const iconv = require('iconv-lite')`.
• decode
  wrong:

  import { decode } from 'iconv-lite'

  correct:

  import iconv from 'iconv-lite'; iconv.decode(buffer, 'utf8')

  `decode` and `encode` are methods on the default `iconv` object, not named exports directly from the package root in v0.x. This might change in v1.x.
• IconvOptions

  import type { IconvOptions } from 'iconv-lite'

  Type imports are crucial for TypeScript users, providing definition for options objects and return types.

Quickstart

This quickstart demonstrates how to encode a JavaScript string into a Buffer using different character sets (UTF-8, Windows-1251) and then decode those Buffers back into strings. It also shows how to check for supported encodings.

import iconv from 'iconv-lite';

// --- Encoding a string to a Buffer ---
const inputString = 'Hello, world! Это тест.';
const utf8Buffer = iconv.encode(inputString, 'utf8');
console.log('UTF-8 Buffer:', utf8Buffer.toString('hex'));

const win1251Buffer = iconv.encode(inputString, 'windows-1251');
console.log('Windows-1251 Buffer:', win1251Buffer.toString('hex'));

// --- Decoding a Buffer to a string ---
const decodedUtf8 = iconv.decode(utf8Buffer, 'utf8');
console.log('Decoded UTF-8:', decodedUtf8);

const decodedWin1251 = iconv.decode(win1251Buffer, 'windows-1251');
console.log('Decoded Windows-1251:', decodedWin1251);

// --- Check if an encoding is supported ---
const supportsUtf8 = iconv.encodingExists('utf8');
console.log('Supports UTF-8:', supportsUtf8);

const supportsFoo = iconv.encodingExists('foo-bar-encoding');
console.log('Supports foo-bar-encoding:', supportsFoo);