Skip to content
Package78 repository health

iconv-lite

Pure JavaScript character encoding conversion supporting hundreds of legacy and Unicode encodings, with streaming for Node.js and browsers.

Library npmv0.7.33,185 stars MIT License
npm install iconv-lite
View source

Repository health

Pre-computed score based on development activity, maintenance, community, maturity, and trend momentum.How we score it →
Good
  • Development activity84
  • Maintenance60
  • Community68
  • Maturity60
  • Momentum40

Technical analysis

AI-assessed by reading the actual repository — architecture, code quality, innovation, and documentation.How we score it →
Excellent
  • Architecture85
  • Code quality92
  • Innovation70
  • Learning curve75

iconv-lite is a pure-JavaScript character encoding conversion library that encodes and decodes buffers to and from strings across hundreds of encodings, from Unicode variants like UTF-8, UTF-16, UTF-32, and UTF-7 to legacy singlebyte and multibyte code pages (Windows-125x, ISO-8859, IBM/DOS, Macintosh, KOI8, Shift_JIS, GBK, Big5, and more). It requires no native code compilation, so it installs quickly and runs unmodified on Windows, in sandboxed environments, and in the browser via bundlers like webpack or Browserify.

Widely depended on by projects such as Express.js’s body-parser, Grunt, Nodemailer, and Yeoman, iconv-lite exposes a simple encode()/decode() API plus a Streaming API built on Node’s stream.Transform for converting large payloads chunk by chunk without buffering the whole input in memory.

What You Get

  • A simple encode(str, encoding) / decode(buf, encoding) API that mirrors Node’s built-in Buffer string encodings but covers hundreds more code pages
  • A Streaming API (encodeStream() / decodeStream()) for converting large payloads chunk-by-chunk via Node’s Transform streams, with a .collect(cb) convenience helper
  • Broad encoding coverage: all Node native encodings, additional Unicode forms (UTF-7, UTF-7-IMAP, UTF-16/-32 with BOM-aware endianness detection), and widespread singlebyte/multibyte legacy code pages (Windows-125x, ISO-8859, IBM/DOS, Macintosh, KOI8, CP932/936/949/950, GB2312/GBK/GB18030, Big5, Shift_JIS, EUC-JP)
  • A dual-backend architecture (Node Buffer-based, and a browser/web TextDecoder-based backend) so the same codec logic runs unmodified on the server and in a bundled browser build
  • Bundled TypeScript type definitions, including a generated union type of all supported encoding names for compile-time validation
  • BOM (Byte Order Mark) handling on both encode and decode paths, configurable via stripBOM and addBOM options

Common Use Cases

  • Converting uploaded or legacy files from Windows-125x, ISO-8859, Shift_JIS, GBK, or other regional encodings into UTF-8 strings for processing
  • Decoding HTTP request/response bodies whose Content-Type charset isn’t UTF-8 (the pattern used internally by body-parser for non-UTF-8 form/text bodies)
  • Streaming large binary files or HTTP payloads through an encoding conversion without loading them fully into memory
  • Running character-encoding conversion inside browser bundles (via webpack/Browserify) where native iconv bindings aren’t available
  • Re-encoding strings back into a specific legacy charset for output to systems or files that still expect a non-Unicode encoding

Under The Hood

Architecture

iconv-lite separates codec logic from platform-specific byte/string primitives through a small dependency-injected “backend” interface (setBackend()): backends/node.js implements allocBytes/bytesToResult/allocRawChars/rawCharsToResult on top of Node’s Buffer, while backends/web.js implements the same interface with Uint8Array/ArrayBuffer and TextDecoder, letting one codec implementation run correctly in both Node and browser bundles. lib/index.js is the core: getCodec() resolves an encoding name through _canonicalizeEncoding() (stripping whitespace, control characters, and non-alphanumerics, explicitly guarding against __proto__/constructor prototype-pollution lookups) and walks the encodings map, which can alias through multiple layers before reaching a codec factory function; resolved codecs are cached in _codecDataCache. encodings/index.js aggregates codec/alias definitions from separate modules (internal, utf32, utf16, utf7, sbcs-codec/sbcs-data(-generated), dbcs-codec/dbcs-data, whatwg-aliases) via an explicit, manually-maintained module list rather than dynamic directory scanning, specifically to stay Browserify-compatible. Streaming support (lib/streams.js) is layered on top via enableStreamingAPI(), dependency-injecting Node’s stream module only when present so browser builds aren’t forced to bundle it.

Tech Stack

The published package has zero runtime dependencies — encode/decode logic, all encoding tables, and stream wrapping are implemented entirely in JavaScript. Development tooling includes ESLint via the neostandard shareable config (with a handful of project-specific rule overrides for legacy code compatibility), TypeScript (~5.9) plus @arethetypeswrong/cli to validate the package’s published type exports, c8 for coverage, and mocha as the test runner. A separate generation/ npm workspace regenerates the singlebyte/multibyte encoding-table data from upstream sources (node-iconv, Unicode.org, WHATWG Encoding Standard). The package ships a browser field in package.json that swaps in lib/index-web.js and disables stream for bundlers.

Code Quality

The test suite is extensive — dedicated spec files per encoding family (Big5, GBK, Shift_JIS, Cyrillic, Greek, Turkish, DBCS, SBCS, UTF-7, UTF-16, UTF-32, CESU-8, BOM handling, streams) plus a full Web Platform Tests conformance run (test/wpt) and a webpack bundle smoke test. CI (GitHub Actions) runs linting, the full test suite across environments, a dedicated Node-web-backend test grep, performance benchmarks across Ubuntu/Windows/macOS, TypeScript type-checking via tsc/attw, and CodeQL security scanning. Coverage is enforced at 90% statements/branches/lines and 95% functions via c8 configuration excluding only generated data files and vendored WPT fixtures. Encoding-name resolution is explicitly tested against prototype-pollution style lookups (__proto__, constructor), and the WHATWG decode paths document precise error-replacement semantics rather than leaving them implicit.

API Design The public surface is deliberately small and mirrors Node’s native Buffer encoding API: encode(str, encoding, options) and decode(buf, encoding, options) as the primary entry points, with encodingExists() for capability checks and lower-level getEncoder/getDecoder/getCodec for advanced use. Options objects (stripBOM, addBOM, defaultEncoding) are opt-in with sensible defaults, and the Streaming API is intentionally not auto-enabled in browser bundles (avoiding ~100KB of unwanted stream shim code) unless a consumer explicitly calls enableStreamingAPI(require('stream')), which the bundled TypeScript definitions document inline.

Used by 18 apps in this directory

Every app whose dependencies include iconv-lite, nine to a page.

Showing 18 apps
Rust 77%MIT

Bun

96,668

Developer Tools

An all-in-one JavaScript and TypeScript toolkit — one Rust-and-JavaScriptCore binary that replaces Node.js, npm, a bundler, and a test runner with faster equivalents.

App
Built with
  • Rust 77%
  • C++ 12%
Updated 1 weeks agoView details
TypeScript 99%AGPL 3.0

Cherry Studio

53,308

AI Assistants

All-in-one AI desktop client with 300+ assistants and multi-model support

App
Built with
  • TypeScript 99%
Updated 1 weeks agoView details
TypeScript 98%Apache 2.0

Cline

71,410

AI Code Assistants

An open-source AI coding agent that lives in your editor and terminal — reads and edits your codebase, runs commands, browses the web, and requires human approval for every action by default.

App
Built with
  • TypeScript 98%
Updated 1 weeks agoView details
C++ 53%Other

Cocos Engine

9,907

Design Tools · Developer Tools · Game Development

Open-source, cross-platform 2D/3D game engine with Vulkan, Metal, and WebGL support for web, mobile, and instant gaming platforms

App
Built with
  • C++ 53%
  • TypeScript 34%
Updated 3 weeks agoView details
TypeScript 84%Apache 2.0

Continue

36,427

AI Code Assistants · AI Development · Automation

Open-source coding agent for VS Code, JetBrains, and CLI with support for 30+ LLM providers.

App
Built with
  • TypeScript 84%
Updated 2 weeks agoView details
TypeScript 89%Other

FastGPT

30,000

AI Agents · AI Development

Build, debug, and deploy knowledge-based AI agents with a visual workflow editor, RAG retrieval, and support for any OpenAI-compatible LLM.

App
Built with
  • TypeScript 89%
Updated 1 weeks agoView details
TypeScript 64%MIT

Ghost

55,701

Blogging · CMS

Open source headless Node.js CMS for professional publishing, paid memberships, and newsletters with a fully owned audience.

App
Built with
  • TypeScript 64%
  • JavaScript 33%
Updated 1 weeks agoView details
TypeScript 98%MPL 2.0

Logto

14,851

Authentication

Open-source auth infrastructure for SaaS and AI apps with OIDC, SAML, and RBAC

App
Built with
  • TypeScript 98%
Updated 2 weeks agoView details
TypeScript 88%Apache 2.0

Medplum

2,785

Authentication · Databases · Developer Tools

An open-source, FHIR-native healthcare platform that gives developers a compliant backend, authentication, a React component library, and serverless bots to build clinical applications in weeks instead of years.

App
Built with
  • TypeScript 88%
Updated 1 weeks agoView details

Join founders building with open source

Opinionated takes, migration guides, cost-saving tips, and insights from the open source ecosystem.

Subscribe on SubstackJoin 750+ subscribers