icu-minify

library4.11.0jsnpmunverified

ICU message format compiler that converts ICU strings into a compact JSON array representation at build time, with a runtime bundle of only 650 bytes (minified + compressed) and zero runtime dependencies. Version 4.11.0 is current, released under the next-intl monorepo with frequent updates (multiple releases per month). Key differentiators: extremely small runtime footprint, full ICU support (plural, select, selectordinal, date, time, number, tags), and TypeScript-first design. Unlike alternatives like icu-to-json or @lingui/message-utils, icu-minify offers first-class ESM support, no polyfills needed, and seamless integration with next-intl.

serialization

npm install icu-minify

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · ICU-MINIFY

icu-minify

serializationjavascriptv4.11.0

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

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

compile

✓ import compile from 'icu-minify/compile';

✗ import { compile } from 'icu-minify';

compile is a default export from a subpath, not a named export from the main entry.

format

✓ import format from 'icu-minify/format';

✗ const format = require('icu-minify/format');

format is also a default export; require() works but is discouraged in ESM projects.

ICUCompiledMessage

✓ import type { ICUCompiledMessage } from 'icu-minify/format';

✗ import { ICUCompiledMessage } from 'icu-minify';

Type-only import from the format subpath; not exported from main package entry.

Compiles an ICU message string at build time and formats it at runtime with arguments.

import compile from 'icu-minify/compile'; import format from 'icu-minify/format'; // Build-time compilation const compiled = compile('Hello {name}! You have {count, plural, one {# message} other {# messages}}.'); console.log(compiled); // ["Hello ",["name"],"! You have ",["count","plural","one",[["#"]],"other",[["#"]]],"."] // Runtime formatting const result = format(compiled, 'en', { name: 'Alice', count: 1 }); console.log(result); // "Hello Alice! You have 1 message."

icu-minify --version

Debug

Known issues

gotchacompile() expects a valid ICU message string; invalid syntax throws at build time, not runtime.

fix

Validate ICU syntax with a linter like intl-messageformat-parser before compilation.

affects: >=4.0.0

gotchaThe format() function locale argument must be a BCP 47 tag (e.g., 'en-US', not 'en_US').

fix

Use Intl.getCanonicalLocales() to normalize locale strings.

affects: >=4.0.0

breakingIn v4.0.0, the package moved to subpath exports; 'icu-minify' no longer exports compile or format directly.

fix

Update imports to 'icu-minify/compile' and 'icu-minify/format'.

affects: >=4.0.0

deprecatedThe 'icu-minify/format' runtime does not support custom locale data; relies on Intl APIs.

fix

Ensure your environment supports Intl.NumberFormat and Intl.DateTimeFormat for the locales you use.

affects: >=4.0.0

gotchaTags in ICU messages (e.g., <bold>text</bold>) require a tags argument in format().

fix

Pass a tags object like { bold: (text) => `<b>${text}</b>` } as the fourth argument.

affects: >=4.0.0

gotchaThe compiled output is an array; do not modify it after build as it affects all references.

fix

Treat compiled messages as immutable constants.

affects: >=4.0.0

Errors

Common errors & fixes

Cannot find module 'icu-minify/compile'

Package version <4.0.0 or subpath exports not supported by module resolver.

fix

Upgrade to icu-minify@4.0.0+ and ensure node version supports exports field (Node >=12.7).

TypeError: compile is not a function

Using named import { compile } instead of default import.

fix

Change import to: import compile from 'icu-minify/compile';

Error: [ICU Minify] Invalid ICU message at position X

ICU syntax error (e.g., unmatched braces, incorrect plural syntax).

fix

Use a linter or parser to validate the ICU string before passing to compile().

TypeError: Cannot read properties of undefined (reading 'format')

format() called with a locale that has no Intl support or wrong argument order.

fix

Ensure locale is a string and that Intl.DateTimeFormat/NumberFormat supports it. Check arguments: format(compiled, locale, values, tags?).

Upgrade

Version history

4.11.0latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

2 hits · last 30 days

node

Resources

githubhttps://github.com/amannn/next-intl ↗

packagehttps://www.npmjs.com/package/icu-minify ↗

homepagehttps://next-intl.dev ↗