Registry / productivity / intl-formatter

intl-formatter

library1.0.3jsnpmunverified

Zero-dependency isomorphic Intl formatting library for JavaScript and TypeScript. Provides seven synchronous, crash-safe methods for numbers, currency, percentages, durations, dates, and relative time with consistent output across server and client (no hydration mismatches). Uses built-in LRU caching for Intl instances. Supports Node.js >=18, React, Next.js App Router, Express, Bun, Deno, and edge runtimes. Under 3KB gzipped. Current stable version: 1.0.3. Release cadence: irregular. Key differentiator: universal runtime support, zero dependencies, and no framework lock-in.

productivity

npm install intl-formatter

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · INTL-FORMATTER

intl-formatter

productivityjavascriptv1.0.3

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.

createFormatter

✓ import { createFormatter } from 'intl-formatter'

✗ const createFormatter = require('intl-formatter')

ESM-only since v1.0.0; package.json 'type': 'module' requires import statement.

Formatter

✓ import type { Formatter } from 'intl-formatter'

✗ import { Formatter } from 'intl-formatter'

Formatter is a TypeScript type/interface, not a runtime value. Use type import to avoid bundler warnings.

FormatterConfig

✓ import type { FormatterConfig } from 'intl-formatter'

✗ import { FormatterConfig } from 'intl-formatter'

FormatterConfig is a TypeScript type, not a runtime export.

Create a formatter with locale 'en-US' and USD currency, then demonstrate all formatting methods.

import { createFormatter } from 'intl-formatter'; const fmt = createFormatter({ locale: 'en-US', currency: 'USD', rules: { compactThreshold: 10000, minimumFractionDigits: 0, maximumFractionDigits: 2, }, }); const numberResult = fmt.number(1500000); // '1.5M' const currencyResult = fmt.currency(49.9); // '$49.9' const percentageResult = fmt.percentage(12.5); // '12.5%' const durationResult = fmt.duration(5400); // '1h 30m' const dateResult = fmt.date(new Date()); // e.g., 'Jan 15, 2024' const relativeTimeResult = fmt.relativeTime(new Date(Date.now() - 60000)); // '1 minute ago' console.log({ numberResult, currencyResult, percentageResult, durationResult, dateResult, relativeTimeResult });

Debug

Known issues

gotchacreateFormatter must be called outside React components to avoid recreating Intl instances on every render.

fix

Define the formatter at module level or memoize with useMemo and stable dependency array.

affects: >=1.0.0

breakingVersion 1.0.0 dropped support for Node <18. Using this package on Node 16 or earlier will fail at runtime (missing Intl support).

fix

Upgrade to Node >=18 or use a polyfill like @formatjs/intl.

affects: >=1.0.0

deprecatedThe package is ESM-only from v1.0.0; require() will throw a module not found error.

fix

Use import syntax or dynamic import() instead of require.

affects: >=1.0.0

gotchaAll formatting methods are crash-safe but return the configured fallback string (default '—') on invalid input, which might be mistaken for a valid result.

fix

Check input validity before formatting or set a distinguishable fallback value like '__INVALID__'.

affects: >=1.0.0

gotchaThe 'duration' method expects value in seconds; passing milliseconds will produce incorrect output.

fix

Convert milliseconds to seconds before calling duration(): fmt.duration(milliseconds / 1000).

affects: >=1.0.0

Errors

Common errors & fixes

ReferenceError: module is not defined in ES module scope

Using require() to import the package in an ESM context (package.json 'type': 'module').

fix

Replace require('intl-formatter') with import { createFormatter } from 'intl-formatter'.

TypeError: createFormatter is not a function

Default import used instead of named import.

fix

Change import createFormatter from 'intl-formatter' to import { createFormatter } from 'intl-formatter'.

Error: Intl is not defined

App running on Node.js version <18 or in a runtime without full Intl support.

fix

Upgrade to Node >=18 or include polyfill @formatjs/intl.

Uncaught TypeError: fmt.number is not a function

createFormatter returned undefined or null because config was invalid (e.g., misspelled property).

fix

Check that createFormatter receives an object with locale, currency (if used), and optional rules. Ensure no typo like 'loacle'.

Upgrade

Version history

1.0.3latest on npm

Audit

Dependencies

@formatjs/intloptionaloptional peer dependency for locale-specific polyfills (e.g., older Node or ICU data)

Agent activity

24 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/gauravgorade/intl-formatter ↗

packageintl-formatter ↗

homepagehttps://gauravgorade.github.io/intl-formatter/ ↗