dinero-best-practices

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

Quick Reference

1. Object Creation (CRITICAL)

• creation-minor-units - Always pass amounts as integers in minor currency units
• creation-from-floats - Use a helper to convert float inputs to minor units
• creation-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 value
• arithmetic-allocate-not-divide - Use allocate for splitting money, not manual division
• arithmetic-scaled-amounts - Never multiply by a raw decimal; use scaled amounts
• arithmetic-percentages - Calculate percentages with allocate or scaled multiply

3. Precision (HIGH)

• precision-bigint - Use dinero.js/bigint for amounts exceeding Number.MAX_SAFE_INTEGER
• precision-crypto - Cryptocurrencies require bigint due to high exponents
• precision-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-shaking
• imports-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