Open Source Platform for DTC, B2B Commerce, Marketplaces & Omnichannel. REST APIs, TypeScript SDKs, and production-ready Next.js storefront. Self-host it. Own your data. No vendor lock-in. Zero platform fees.
@spree/core
The shared foundation of Spree Commerce for TypeScript and JavaScript: the code lists the Spree API speaks, exact money arithmetic, and the filter vocabulary of its list endpoints.
It has no dependencies and makes no network calls, so it runs anywhere JavaScript does: browsers, Node.js, edge runtimes, React Native and build scripts. The Store, Admin and Seller SDKs are built on it and re-export its code lists and money helpers. Install it on its own when you need those without an API client — in a checkout widget, a feed generator, a test suite or your own backend.
npm install @spree/core
@spree/core is released with Spree and carries its version: @spree/[email protected] works with Spree 6.0.x.
Contents
- Code lists — countries, currencies, locales, weight and dimension units, and checking a code you received
- Statuses and kinds — every status and kind the API returns, and picking the ones an action accepts
- Unit systems — which weight units belong to metric and imperial
- Display names — country, currency and language names in any language
- Money — exact arithmetic, percentages and formatting for decimal-string amounts
- Reading typed amounts — turning "1.234,56" into "1234.56"
- Filters — types for the queries Spree list endpoints accept
- Random IDs — UUIDs that also work on plain-HTTP pages
- Compatibility
Code lists
Every country, currency, locale and unit Spree accepts, as closed lists generated from the Spree API reference. Each list is both a value you can iterate and a type, and every code is documented with its English name, so your editor shows "US Dollar" when you hover USD.
| List | Contains | Example |
|---|---|---|
CountryCode |
240 ISO 3166-1 alpha-2 country codes | CountryCode.US → 'US' |
CurrencyCode |
178 ISO 4217 currency codes | CurrencyCode.EUR → 'EUR' |
LocaleCode |
202 locale codes | LocaleCode.pt_BR → 'pt-BR' |
WeightUnit |
g, kg, lb, oz |
WeightUnit.kg → 'kg' |
DimensionUnit |
mm, cm, in, ft |
DimensionUnit.cm → 'cm' |
import { CurrencyCode, WeightUnit } from '@spree/core';
// As a type: only codes Spree accepts compile.
function setCurrency(currency: CurrencyCode) {}
setCurrency('EUR');
setCurrency('EURO'); // Type error
// As a value: build a picker from the full list.
const options = Object.values(WeightUnit); // ['g', 'kg', 'lb', 'oz']
A locale with a region uses a hyphen in its value and an underscore in its key, so LocaleCode.pt_BR is 'pt-BR'.
Checking a code you received
isCountryCode, isCurrencyCode and isLocaleCode check a value's shape and narrow its type, so a plain string from a form, a URL or a file becomes a typed code:
import { isCountryCode } from '@spree/core';
const country = new URLSearchParams(location.search).get('country');
if (isCountryCode(country)) {
// country is a CountryCode here
}
They check the shape only, US but not us or USA, and accept a code missing from the lists above. The Spree server holds the authoritative list and rejects a code it does not know, so a client built with an older or newer version of this package still accepts what its server does.
Currencies still in use
CurrencyCode includes replaced currencies, such as the Croatian kuna, so that amounts recorded in them stay valid. ACTIVE_CURRENCY_CODES leaves them out, for a picker offering any currency for new prices, and RETIRED_CURRENCY_CODES lists the ones it leaves out.
Statuses and kinds
Every status, kind and other value list the Spree API returns — ProductStatus, PaymentStatus, FeeKind, MediaType and the rest — generated from the API itself. Each comes as a list of its built-in values and a type:
import { PRODUCT_STATUSES, type ProductStatus } from '@spree/core';
PRODUCT_STATUSES; // ['draft', 'active', 'archived', 'proposed', 'rejected']
// A filter built from the list stays complete when Spree adds a status.
const options = PRODUCT_STATUSES.map((status) => ({ value: status, label: t(status) }));
Statuses and kinds an extension may add to — ProductStatus, PaymentStatus, FeeKind and the like — are open: the type still accepts any string, while your editor suggests the built-in ones. The rest are closed, like the code lists: OrderPaymentStatus, MediaType, DiscountKind and every other list the API never grows accept only their own values.
When only some values matter — the statuses an action accepts, say — pick them with subsetOf. A misspelled or retired value fails to compile, and includes takes any status the API returns:
import { RETURN_STATUSES, subsetOf } from '@spree/core';
const ACTIONABLE = subsetOf(RETURN_STATUSES, ['requested', 'approved', 'received']);
subsetOf(RETURN_STATUSES, ['requsted']); // Type error
if (ACTIONABLE.includes(ret.status)) {
// show the actions
}
The SDKs re-export the types each of them uses, so import type { PaymentStatus } from '@spree/sdk' works too.
Unit systems
A Spree store uses either the metric or the imperial system. UNIT_SYSTEM_WEIGHT_UNITS lists the weight units each one offers, the usual one first, so a settings screen can offer only the units that fit:
import { UNIT_SYSTEMS, UNIT_SYSTEM_WEIGHT_UNITS, type UnitSystem } from '@spree/core';
UNIT_SYSTEMS; // ['metric', 'imperial']
UNIT_SYSTEM_WEIGHT_UNITS.metric; // ['kg', 'g']
UNIT_SYSTEM_WEIGHT_UNITS.imperial; // ['lb', 'oz']
Display names
intlDisplayName names a country, currency, language or other code in the reader's language, falling back to English:
import { intlDisplayName } from '@spree/core';
intlDisplayName('region', 'de', 'US'); // 'Vereinigte Staaten'
intlDisplayName('currency', 'fr', 'JPY'); // 'yen japonais'
intlDisplayName('language', 'en', 'pt-BR'); // 'Brazilian Portuguese'
It answers undefined when the runtime has no name for a code or the code is malformed, so you choose the fallback, usually the code itself: intlDisplayName('region', locale, code) ?? code.
localeEndonym names a language in that language itself, for a language picker where every reader finds their own language:
import { localeEndonym } from '@spree/core';
localeEndonym('de'); // 'Deutsch'
localeEndonym('fr'); // 'Français'
Money
Spree sends and accepts every amount as a decimal string such as "1234.56", never as a JavaScript number. A number cannot hold most decimal amounts exactly (0.1 + 0.2 is 0.30000000000000004), and those errors grow into lost cents on totals, refunds and payouts.
These helpers work on the strings directly, without converting them to numbers, so every result is exact:
import { sumMoney, subtractMoney, multiplyMoney, compareMoney, formatMoney } from '@spree/core';
const subtotal = sumMoney(['19.99', '5.01'], 'USD'); // '25.00'
const lineTotal = multiplyMoney('9.99', 3, 'USD'); // '29.97'
const balance = subtractMoney('10.00', '0.01'); // '9.99'
if (compareMoney(subtotal, '25.00') >= 0) {
// free shipping
}
formatMoney(subtotal, 'USD', 'en-US'); // '$25.00'
| Function | What it does |
|---|---|
sumMoney(values, currency?) |
Adds amounts. Blank values (null, undefined, '') count as zero. |
subtractMoney(a, b, currency?) |
a minus b. |
multiplyMoney(value, quantity, currency?) |
An amount times a whole number. A fractional quantity throws an error. |
negateMoney(value) |
Flips the sign: '5.00' → '-5.00'. |
compareMoney(a, b) |
-1, 0 or 1. Decimals don't matter: '10.0' equals '10.00'. |
isZeroMoney(value) |
Whether an amount is zero. Blank values count as zero. |
isDecimalString(value) |
Whether a value is a plain decimal string. '19.99' is; '19,99' and the number 19.99 are not. |
decimalPlaces(currency) |
How many decimals a currency uses: 2 for USD, 0 for JPY, 3 for KWD. An unknown code answers 2. |
formatMoney(amount, currency, locale?, options?) |
Formats an amount for display in a language. |
isPositiveMoney(value) |
Whether an amount is above zero. Blank or malformed values are not. |
Percentages and shares
Rates travel as decimal strings too. These helpers convert and apply them without floating point, rounding the result once, half away from zero, to the currency's decimals:
import { percentOf, prorateMoney, fractionToPercent, percentToFraction } from '@spree/core';
percentOf('19.99', '10', 'USD'); // '2.00' — 10% of $19.99
prorateMoney('10.00', 1, 3, 'USD'); // '3.33' — the share 1 of 3 units carries
fractionToPercent('0.23'); // '23' — a stored rate as a merchant reads it
percentToFraction('7.25'); // '0.0725' — a typed percentage as the API stores it
shiftDecimalPoint(value, places) moves the decimal point by whole places, exactly: shiftDecimalPoint('0.077', 2) is '7.7'.
Nothing is rounded away
Arithmetic never rounds. A result keeps the most decimals any input has and, when you pass a currency, at least that currency's decimals:
sumMoney(['1.5', '2.5'], 'USD'); // '4.00' — padded to the currency's 2 decimals
sumMoney(['1000'], 'JPY'); // '1000' — the yen has no decimals
multiplyMoney('19.9990', 3); // '59.9970' — a unit price keeps its 4 decimals
Rounding happens once, when you display the amount.
Formatting
formatMoney shows an amount in a currency and language, using the currency's own number of decimals:
formatMoney('1234.5', 'USD', 'en-US'); // '$1,234.50'
formatMoney('1234.5', 'EUR', 'de-DE'); // '1.234,50 €'
formatMoney('1500', 'JPY', 'ja-JP'); // '¥1,500'
formatMoney('0.0125', 'USD', 'en-US', { unitPrice: true }); // '$0.0125'
- Leave out the locale to use the reader's own language.
unitPrice: truekeeps up to 4 decimals, for prices per gram or per unit.- A missing or malformed amount formats as an empty string, so a page never shows
NaN. - An amount that rounds to zero shows no minus sign:
'-0.001'formats as'$0.00'.
CURRENCY_EXPONENTS exposes the full currency decimals table. The Spree server reads the same table, so the server and your client always agree on a currency's decimals.
Reading typed amounts
People type amounts in their own number format: a German writes 1.234,56, a French person 1 234,56. Spree accepts only 1234.56, and never guesses on the server. Convert input in the same language the field is displayed in:
import { normalizeMoneyInput, currencyParts } from '@spree/core';
normalizeMoneyInput('1.234,56', 'de'); // '1234.56'
normalizeMoneyInput('1 234,56', 'fr'); // '1234.56'
normalizeMoneyInput('19.50', 'de'); // '19.50' — a period before two digits is a decimal point
normalizeMoneyInput(' ', 'en'); // ''
currencyParts('EUR', 'de'); // { symbol: '€', decimal: ',' } — to label the input
The result is always a plain decimal string or '', never a number, so nothing is lost on the way to the API.
Filters
Spree list endpoints accept filters named after an attribute and a condition: name_cont (name contains), price_gteq (price at least), status_in (status is one of), deleted_at_null (not deleted). These types build exact TypeScript types for those queries, so a misspelled filter or a value of the wrong kind fails to compile.
The SDKs already type every list method this way. Use these types to describe queries of your own, such as a saved search or a URL you build by hand:
import type { RangeFilters, SortKey, TextFilters } from '@spree/core';
type ProductQuery = TextFilters<'name' | 'sku'> &
RangeFilters<'price'> & {
sort?: SortKey<'name' | 'price' | 'created_at'>;
};
const query: ProductQuery = {
name_cont: 'shirt',
price_gteq: '10.00',
sort: '-price',
};
| Type | For | Conditions |
|---|---|---|
TextFilters<Attribute> |
Text | eq, not_eq, cont, i_cont, not_cont, start, end, in, not_in, null, not_null, present, blank |
RangeFilters<Attribute, Value?> |
Amounts, counts, dates and times | eq, not_eq, lt, lteq, gt, gteq, in, not_in, null, not_null |
EnumFilters<Attribute, Value> |
A known set of values that extensions may add to, such as statuses | eq, not_eq, in, not_in, null, not_null |
CodeFilters<Attribute, Code> |
A closed code list, such as CurrencyCode |
eq, not_eq, in, not_in, null, not_null |
IdFilters<Attribute> |
Record IDs, such as prod_86Rf07xd4z |
eq, not_eq, in, not_in, null, not_null |
BooleanFilters<Attribute> |
True or false | eq, not_eq, in, not_in, true, false, null |
Prefixed<Prefix, Filters> |
Filters on an associated record, such as variants_sku_eq |
— |
SortKey<Attribute> |
Sorting: 'name', descending '-name', or two fields 'name,-price' |
— |
Amounts in RangeFilters are decimal strings, like everywhere else in Spree. FILTER_PREDICATES lists the conditions for each kind of value, if you need them at runtime, for example to build a filter editor, and FilterPredicate is the type of any one of them.
Random IDs
randomUUID() returns a version 4 UUID. Browsers only provide crypto.randomUUID on secure pages (HTTPS or localhost), so code that runs on a page served over plain HTTP, for example at a server's IP address, should use this instead. It falls back to crypto.getRandomValues, which every browser provides.
import { randomUUID } from '@spree/core';
randomUUID(); // '3b241101-e2bb-4255-8caf-4136c566a962'
Compatibility
- ES modules and CommonJS, with TypeScript types included.
- Node.js 18 or later, and every current browser.
formatMoneyuses the built-inIntl.NumberFormat.randomUUIDneeds the Web Crypto API as the globalcrypto: built into browsers and Node.js 19 or later. Node.js 18 needs the--experimental-global-webcryptoflag, and React Native needs a polyfill.
Links
License
MIT