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
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
StringEncoding
✓ import { StringEncoding } from 'iconv-corefoundation'
✗ import StringEncoding from 'iconv-corefoundation'
Named export, not default. Must be imported using named import syntax.
transcode
✓ import { transcode } from 'iconv-corefoundation'
✗ const transcode = require('iconv-corefoundation').transcode
ESM style works, but also available via CJS. TypeScript friendly with types.
encodeSmallest
✓ import { encodeSmallest } from 'iconv-corefoundation'
✗ const { encodeSmallest } = require('iconv-corefoundation')
Both ESM and CJS imports work. The named export is correct.
Demonstrates encoding/decoding and transcoding with StringEncoding and transcode function.
import { StringEncoding, transcode } from 'iconv-corefoundation';
// Get Mac OS Roman encoding
const macRoman = StringEncoding.byIANACharSetName('macintosh');
// Encode a string
const buf = macRoman.encode('Hello, world!');
console.log(buf); // <Buffer ...>
// Decode back
const str = macRoman.decode(buf);
console.log(str); // 'Hello, world!'
// Transcode directly between buffers (no JS string)
const utf8Buf = Buffer.from('Hello, world!', 'utf8');
const latin1 = StringEncoding.byCFStringEncoding(0x0600); // kCFStringEncodingISOLatin1
const latin1Buf = transcode(utf8Buf, null, latin1); // null means UTF-8
console.log(latin1Buf);
Errors
Common errors & fixes
Error: The module 'iconv-corefoundation' was compiled against a different Node.js version using NODE_MODULE_VERSION 64. This version of Node.js requires NODE_MODULE_VERSION 72.
Pre-compiled binary incompatible with current Node.js version (e.g., Node 12 vs Node 14).
fixRebuild native addon: npm rebuild iconv-corefoundation
TypeError: Class constructor StringEncoding cannot be invoked without 'new'
Attempted to call StringEncoding() as a function instead of using static methods.
fixUse StringEncoding.byCFStringEncoding(...) or similar static method.
Error: Dynamic loading not supported: this module works only on macOS
Tried to use the package on non-macOS system.
fixDo not import on non-macOS platforms. Use conditional require: if (process.platform === 'darwin') { ... } Error: Could not locate the bindings file. Tried: ...
Native addon .node file missing or not installed properly.
fixReinstall package: npm install iconv-corefoundation
Audit
Dependencies
node-gypoptionalRequired for building native addon (pre-compiled binaries provided for macOS, but fallback build may need node-gyp)