icu-minify

4.11.0 verified Fri May 01 auth: no javascript

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.

Common errors

error Cannot find module 'icu-minify/compile' ↓

cause 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).

error TypeError: compile is not a function ↓

cause Using named import { compile } instead of default import.

fix

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

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

cause 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().

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

cause 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?).

Warnings

gotcha compile() 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.

gotcha The 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.

breaking In 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'.

deprecated The '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.

gotcha Tags 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.

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

fix Treat compiled messages as immutable constants.

Install

npm install icu-minify

yarn add icu-minify

pnpm add icu-minify

Imports

compile
wrong
```
import { compile } from 'icu-minify';
```
correct
```
import compile from 'icu-minify/compile';
```
compile is a default export from a subpath, not a named export from the main entry.
format
wrong
```
const format = require('icu-minify/format');
```
correct
```
import format from 'icu-minify/format';
```
format is also a default export; require() works but is discouraged in ESM projects.

ICUCompiledMessage

wrong

import { ICUCompiledMessage } from 'icu-minify';

correct

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

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

Quickstart

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