Currency Formatter

Common errors

• TypeError: currencyFormatter.format is not a function

  cause Attempting to use an ES module default import (e.g., `import currencyFormatter from 'currency-formatter'`) in an environment or bundler configuration where the `currency-formatter` package is treated as a CommonJS module without a compatible default export for ESM.
  fix Use the CommonJS `require` syntax: `const currencyFormatter = require('currency-formatter');`.

• My currency formatting is incorrect or doesn't match native browser behavior for certain locales/currencies.

  cause Discrepancies between `currency-formatter`'s internal locale data or formatting logic and the more current/standardized behavior of the `Intl.NumberFormat` API, or incorrect `code`/`locale` options provided.
  fix For modern applications, transition to `Intl.NumberFormat` for accurate and up-to-date internationalization. If `currency-formatter` must be used, ensure `code` and `locale` options are precisely configured and thoroughly test all target currencies/locales.

• My JavaScript bundle size increased significantly after adding currency-formatter.

  cause The library is included in the production build even if its functionality is redundant because the target environments natively support `Intl.NumberFormat`.
  fix Evaluate your project's `Intl.NumberFormat` support requirements. If modern browser/Node.js support is sufficient, remove `currency-formatter` and use native APIs. For legacy support, consider conditional loading or a more granular polyfill.

Warnings

• breaking This library is explicitly deprecated by its own maintainers. The README strongly advises against its use for most modern applications, recommending the native `Intl.NumberFormat` API instead.
  Fix: Migrate currency formatting logic to `new Intl.NumberFormat(locale, options).format(value)` for robust internationalization. Consider polyfilling `Intl.js` for environments that absolutely require support for older browsers.
• gotcha Including `currency-formatter` may unnecessarily increase your application's bundle size if your target environments already support the native `Intl.NumberFormat` API.
  Fix: Before adding this dependency, verify the `Intl.NumberFormat` support in your target browsers and Node.js versions (e.g., via `caniuse.com`). If support is adequate, remove `currency-formatter`.
• gotcha Formatting results from `currency-formatter` may differ from those produced by the native `Intl.NumberFormat` API due to different underlying implementations and locale data, potentially leading to inconsistent UI.
  Fix: Choose a single, consistent approach for currency formatting across your application. For new projects and modern environments, `Intl.NumberFormat` is the recommended standard. For legacy support, ensure thorough testing with `currency-formatter`.
• gotcha The `unformat` function's behavior relies heavily on the provided `code` or `locale` parameters to correctly parse monetary strings, and may produce unexpected results if these do not match the input string's format.
  Fix: Always provide the correct `code` or `locale` option to `currencyFormatter.unformat()` that corresponds to the format of the string being parsed. Test thoroughly with various locale-specific inputs.

Install

• npm install currency-formatter npm
• yarn add currency-formatter yarn
• pnpm add currency-formatter pnpm

Imports

• currencyFormatter
  wrong:

  import currencyFormatter from 'currency-formatter';

  correct:

  const currencyFormatter = require('currency-formatter');

  This library is primarily CommonJS. While bundlers might allow `import`, `require` is the intended and most reliable way to import.
• format
  wrong:

  import { format } from 'currency-formatter';

  correct:

  const { format } = require('currency-formatter'); // Or currencyFormatter.format(...)

  The `format` function is a method on the default export. Destructuring from `require` works, but directly accessing `currencyFormatter.format` is also common. ESM named imports might fail without proper transpilation.
• findCurrency
  wrong:

  import { findCurrency } from 'currency-formatter';

  correct:

  const { findCurrency } = require('currency-formatter'); // Or currencyFormatter.findCurrency(...)

  Similar to `format`, `findCurrency` is a method on the default CommonJS export. Prefer accessing it via the default `currencyFormatter` object.

Quickstart

Demonstrates basic currency formatting by code and locale, retrieving currency information, and unformatting monetary strings using the CommonJS API.

const currencyFormatter = require('currency-formatter');

// Format a number by currency code
let formattedUSD = currencyFormatter.format(1000000, { code: 'USD' });
console.log(`Formatted USD: ${formattedUSD}`); // Expected: $1,000,000.00

// Format a number by locale
let formattedEUR_de = currencyFormatter.format(1000000, { locale: 'de-DE' });
console.log(`Formatted EUR (de-DE): ${formattedEUR_de}`); // Expected: 1.000.000,00 €

// Get currency information
let usdInfo = currencyFormatter.findCurrency('USD');
console.log('USD Currency Info:', usdInfo);
/* Expected: {
 *   code: 'USD',
 *   symbol: '$',
 *   thousandsSeparator: ',',
 *   decimalSeparator: '.',
 *   symbolOnLeft: true,
 *   spaceBetweenAmountAndSymbol: false,
 *   decimalDigits: 2
 * } */

// Unformat a monetary string
let unformattedUSD = currencyFormatter.unformat('$1,000,000.00', { code: 'USD' });
console.log(`Unformatted USD: ${unformattedUSD}`); // Expected: 1000000

let unformattedEUR = currencyFormatter.unformat('1.000.000,00 €', { locale: 'de-DE' });
console.log(`Unformatted EUR: ${unformattedEUR}`); // Expected: 1000000.00