{"id":11072,"library":"iconv-lite","title":"iconv-lite - Character Encoding Conversion","description":"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`.","status":"active","version":"0.7.2","language":"javascript","source_language":"en","source_url":"https://github.com/pillarjs/iconv-lite","tags":["javascript","iconv","convert","charset","icu","typescript"],"install":[{"cmd":"npm install iconv-lite","lang":"bash","label":"npm"},{"cmd":"yarn add iconv-lite","lang":"bash","label":"yarn"},{"cmd":"pnpm add iconv-lite","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"The primary `iconv` object is a default export for ESM. In CommonJS, you'd `const iconv = require('iconv-lite')`.","wrong":"import { iconv } from 'iconv-lite'","symbol":"iconv","correct":"import iconv from 'iconv-lite'"},{"note":"`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.","wrong":"import { decode } from 'iconv-lite'","symbol":"decode","correct":"import iconv from 'iconv-lite'; iconv.decode(buffer, 'utf8')"},{"note":"Type imports are crucial for TypeScript users, providing definition for options objects and return types.","symbol":"IconvOptions","correct":"import type { IconvOptions } from 'iconv-lite'"}],"quickstart":{"code":"import iconv from 'iconv-lite';\n\n// --- Encoding a string to a Buffer ---\nconst inputString = 'Hello, world! Это тест.';\nconst utf8Buffer = iconv.encode(inputString, 'utf8');\nconsole.log('UTF-8 Buffer:', utf8Buffer.toString('hex'));\n\nconst win1251Buffer = iconv.encode(inputString, 'windows-1251');\nconsole.log('Windows-1251 Buffer:', win1251Buffer.toString('hex'));\n\n// --- Decoding a Buffer to a string ---\nconst decodedUtf8 = iconv.decode(utf8Buffer, 'utf8');\nconsole.log('Decoded UTF-8:', decodedUtf8);\n\nconst decodedWin1251 = iconv.decode(win1251Buffer, 'windows-1251');\nconsole.log('Decoded Windows-1251:', decodedWin1251);\n\n// --- Check if an encoding is supported ---\nconst supportsUtf8 = iconv.encodingExists('utf8');\nconsole.log('Supports UTF-8:', supportsUtf8);\n\nconst supportsFoo = iconv.encodingExists('foo-bar-encoding');\nconsole.log('Supports foo-bar-encoding:', supportsFoo);","lang":"typescript","description":"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."},"warnings":[{"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`.","message":"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.","severity":"breaking","affected_versions":">=1.0.0-alpha.1"},{"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.","message":"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).","severity":"breaking","affected_versions":">=1.0.0-alpha.1"},{"fix":"Thoroughly test decoding functionality if upgrading to `v1.x` and relying on specific, potentially non-standard decoding behaviors in `v0.x`.","message":"`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.","severity":"breaking","affected_versions":">=1.0.0-alpha.1"},{"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.","message":"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()`.","severity":"gotcha","affected_versions":"<0.7.2"},{"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.","message":"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.","severity":"gotcha","affected_versions":"<0.7.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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'.","cause":"Attempting to encode or decode with an unsupported or misspelled character encoding name.","error":"TypeError: iconv-lite does not support the encoding: foo-bar-encoding"},{"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`.","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.","error":"TS2307: Cannot find module 'iconv-lite' or its corresponding type declarations."},{"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.","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.","error":"TS2305: Module ''iconv-lite'' has no default export."}],"ecosystem":"npm"}