| name | dinero-best-practices |
| description | 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.
|
| license | MIT |
| metadata | {"author":"dinerojs","version":"1.0.0"} |
Dinero.js Best Practices
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.
When to Apply
Reference these guidelines when:
- Creating Dinero objects from user input, API responses, or database values
- Performing arithmetic on monetary values (adding, splitting, multiplying)
- Choosing between
number and bigint calculators
- Importing from
dinero.js, dinero.js/currencies, or dinero.js/bigint
- Working with prices, costs, taxes, or any financial calculation
Rule Categories by Priority
| Priority | Category | Impact | Prefix |
|---|
| 1 | Object Creation | CRITICAL | creation- |
| 2 | Arithmetic | CRITICAL | arithmetic- |
| 3 | Precision | HIGH | precision- |
| 4 | Imports | MEDIUM | imports- |
Quick Reference
1. Object Creation (CRITICAL)
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 directly
2. Arithmetic (CRITICAL)
arithmetic-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 multiply
3. Precision (HIGH)
precision-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 operations
4. Imports (MEDIUM)
imports-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/bigint
How to Use
Read individual rule files for detailed explanations and code examples:
rules/creation-minor-units.md
rules/arithmetic-allocate-not-divide.md
Each rule file contains:
- Brief explanation of why it matters
- Incorrect code example with explanation
- Correct code example with explanation
- Additional context and references
