iconv-lite

library0.7.2jsnpmunverified

iconv-lite is a pure JavaScript library for converting character encodings without relying on native Node.js bindings or external dependencies for core functionality. It provides a robust solution for handling various text encodings, making it suitable for applications that need to process files, network streams, or user input in different character sets. The current stable version is `0.7.2`, with `v1.0.0-alpha.1` being an actively developed upcoming major release introducing significant breaking changes. While there isn't a strict release cadence, the project sees regular maintenance and improvements, including recent type definition enhancements and bug fixes. Its key differentiator is its pure JavaScript implementation, which avoids installation complexities associated with native modules like `node-iconv`.

serialization

npm install iconv-lite

github ↗package ↗

INSTALL

IMPORT

SIG · ICONV-LITE

iconv-lite

serializationjavascriptv0.7.2

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

iconv

✓ import iconv from 'iconv-lite'

✗ 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

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

✗ import { decode } from 'iconv-lite'

`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.

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);

Debug

Known issues

breakingVersion `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`.

affects: >=1.0.0-alpha.1

breakingThe `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.

affects: >=1.0.0-alpha.1

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`.

affects: >=1.0.0-alpha.1

gotchaPrior 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.

affects: <0.7.2

gotchaOlder 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.

affects: <0.7.0

Errors

Common errors & fixes

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

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.

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.

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.

Upgrade

Version history

0.7.2latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

4 hits · last 30 days

node

Resources

githubhttps://github.com/pillarjs/iconv-lite ↗

packagehttps://www.npmjs.com/package/iconv-lite ↗