Core best practices for the Dinero.js money library. Use when writing, reviewing, or refactoring code that creates Dinero objects, performs arithmetic on monetary values, or handles money in JavaScript/TypeScript. Triggers on imports from 'dinero.js', monetary calculations, or price/cost handling logic.
Core rules for working with Dinero.js, the JavaScript/TypeScript library for creating, calculating, and formatting money safely. Contains rules across 4 categories, prioritized by impact.
Reference these guidelines when:
number and bigint calculatorsdinero.js, dinero.js/currencies, or dinero.js/bigint| Priority | Category | Impact | Prefix |
|---|
| 1 | Object Creation | CRITICAL | creation- |
| 2 | Arithmetic | CRITICAL | arithmetic- |
| 3 | Precision | HIGH | precision- |
| 4 | Imports | MEDIUM | imports- |
creation-minor-units - Always pass amounts as integers in minor currency unitscreation-from-floats - Use a helper to convert float inputs to minor unitscreation-zero-exponent - Currencies with exponent 0 (e.g., JPY) take major units directlyarithmetic-immutability - All operations return new objects; capture the return valuearithmetic-allocate-not-divide - Use allocate for splitting money, not manual divisionarithmetic-scaled-amounts - Never multiply by a raw decimal; use scaled amountsarithmetic-percentages - Calculate percentages with allocate or scaled multiplyprecision-bigint - Use dinero.js/bigint for amounts exceeding Number.MAX_SAFE_INTEGERprecision-crypto - Cryptocurrencies require bigint due to high exponentsprecision-trim-scale - Use trimScale to remove trailing zeros after chained operationsimports-tree-shaking - Import only what you use; standalone functions enable tree-shakingimports-bigint-currencies - Match calculator type: use dinero.js/bigint/currencies with dinero.js/bigintRead individual rule files for detailed explanations and code examples:
rules/creation-minor-units.md
rules/arithmetic-allocate-not-divide.md
Each rule file contains: