{"id":25741,"library":"icu-minify","title":"icu-minify","description":"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.","status":"active","version":"4.11.0","language":"javascript","source_language":"en","source_url":"https://github.com/amannn/next-intl","tags":["javascript","icu","messageformat","i18n","internationalization","compiler","minify"],"install":[{"cmd":"npm install icu-minify","lang":"bash","label":"npm"},{"cmd":"yarn add icu-minify","lang":"bash","label":"yarn"},{"cmd":"pnpm add icu-minify","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"compile is a default export from a subpath, not a named export from the main entry.","wrong":"import { compile } from 'icu-minify';","symbol":"compile","correct":"import compile from 'icu-minify/compile';"},{"note":"format is also a default export; require() works but is discouraged in ESM projects.","wrong":"const format = require('icu-minify/format');","symbol":"format","correct":"import format from 'icu-minify/format';"},{"note":"Type-only import from the format subpath; not exported from main package entry.","wrong":"import { ICUCompiledMessage } from 'icu-minify';","symbol":"ICUCompiledMessage","correct":"import type { ICUCompiledMessage } from 'icu-minify/format';"}],"quickstart":{"code":"import compile from 'icu-minify/compile';\nimport format from 'icu-minify/format';\n\n// Build-time compilation\nconst compiled = compile('Hello {name}! You have {count, plural, one {# message} other {# messages}}.');\nconsole.log(compiled);\n// [\"Hello \",[\"name\"],\"! You have \",[\"count\",\"plural\",\"one\",[[\"#\"]],\"other\",[[\"#\"]]],\".\"]\n\n// Runtime formatting\nconst result = format(compiled, 'en', { name: 'Alice', count: 1 });\nconsole.log(result);\n// \"Hello Alice! You have 1 message.\"","lang":"typescript","description":"Compiles an ICU message string at build time and formats it at runtime with arguments."},"warnings":[{"fix":"Validate ICU syntax with a linter like intl-messageformat-parser before compilation.","message":"compile() expects a valid ICU message string; invalid syntax throws at build time, not runtime.","severity":"gotcha","affected_versions":">=4.0.0"},{"fix":"Use Intl.getCanonicalLocales() to normalize locale strings.","message":"The format() function locale argument must be a BCP 47 tag (e.g., 'en-US', not 'en_US').","severity":"gotcha","affected_versions":">=4.0.0"},{"fix":"Update imports to 'icu-minify/compile' and 'icu-minify/format'.","message":"In v4.0.0, the package moved to subpath exports; 'icu-minify' no longer exports compile or format directly.","severity":"breaking","affected_versions":">=4.0.0"},{"fix":"Ensure your environment supports Intl.NumberFormat and Intl.DateTimeFormat for the locales you use.","message":"The 'icu-minify/format' runtime does not support custom locale data; relies on Intl APIs.","severity":"deprecated","affected_versions":">=4.0.0"},{"fix":"Pass a tags object like { bold: (text) => `<b>${text}</b>` } as the fourth argument.","message":"Tags in ICU messages (e.g., <bold>text</bold>) require a tags argument in format().","severity":"gotcha","affected_versions":">=4.0.0"},{"fix":"Treat compiled messages as immutable constants.","message":"The compiled output is an array; do not modify it after build as it affects all references.","severity":"gotcha","affected_versions":">=4.0.0"}],"env_vars":null,"last_verified":"2026-05-01T00:00:00.000Z","next_check":"2026-07-30T00:00:00.000Z","problems":[{"fix":"Upgrade to icu-minify@4.0.0+ and ensure node version supports exports field (Node >=12.7).","cause":"Package version <4.0.0 or subpath exports not supported by module resolver.","error":"Cannot find module 'icu-minify/compile'"},{"fix":"Change import to: import compile from 'icu-minify/compile';","cause":"Using named import { compile } instead of default import.","error":"TypeError: compile is not a function"},{"fix":"Use a linter or parser to validate the ICU string before passing to compile().","cause":"ICU syntax error (e.g., unmatched braces, incorrect plural syntax).","error":"Error: [ICU Minify] Invalid ICU message at position X"},{"fix":"Ensure locale is a string and that Intl.DateTimeFormat/NumberFormat supports it. Check arguments: format(compiled, locale, values, tags?).","cause":"format() called with a locale that has no Intl support or wrong argument order.","error":"TypeError: Cannot read properties of undefined (reading 'format')"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}