dinero-best-practices

Original：🇺🇸 English

Translated

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.

1installs

Sourcedinerojs/dinero.js

Added on2026-03-01

NPX Install

npx skill4agent add dinerojs/dinero.js dinero-best-practices

SKILL.md Content

View Translation Comparison →

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 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