docusaurus-plugin-unirate

Docusaurus v3 plugin for UniRate — fetches a currency exchange-rate snapshot (and optionally the currency catalogue + VAT rates) at build time, exposes it as global plugin data, and ships a small <ExchangeRate /> theme component.

• Build-time snapshot: rates resolve to constants in your static HTML; no client-side API key, no runtime fetch.
• Zero runtime dependencies (uses native fetch).
• Cross-pair conversion derived from a single base, so the payload stays small.
• Full typed error mapping surfaced from the UniRate API.

Install

npm install docusaurus-plugin-unirate

You'll need a free UniRate API key — grab one at https://unirateapi.com.

Configure

// docusaurus.config.js
module.exports = {
  // ...
  plugins: [
    [
      "docusaurus-plugin-unirate",
      {
        apiKey: process.env.UNIRATE_API_KEY,
        baseCurrency: "USD",
        currencies: ["EUR", "GBP", "JPY", "CAD", "AUD"],
      },
    ],
  ],
};

If apiKey is omitted the plugin reads UNIRATE_API_KEY from the environment.

Options

Option	Type	Default	Description
apiKey	string	process.env.UNIRATE_API_KEY	UniRate API key.
baseCurrency	string	"USD"	Base the build-time snapshot is keyed against.
currencies	string[]	all UniRate currencies	Optional allowlist to shrink the exposed payload.
includeVat	boolean	false	Also fetch VAT rates and expose them as vatRates in the snapshot.
apiBaseUrl	string	"https://api.unirateapi.com"	API host. Override for self-hosted or testing.
failOnFetchError	boolean	true	Fail the build if the snapshot fetch fails. Set to false to ship an empty snapshot and let pages fall back gracefully.

The <ExchangeRate /> component

import ExchangeRate from "@theme/ExchangeRate";

100 USD ≈ <ExchangeRate amount={100} from="USD" to="EUR" />
USD → GBP rate: <ExchangeRate from="USD" to="GBP" rateOnly />

Prop	Type	Default	Description
to	string	—	Target currency (required).
from	string	snapshot base	Source currency.
amount	number	1	Amount to convert (ignored when rateOnly).
rateOnly	boolean	false	Render the raw to-per-1-from rate instead of a formatted amount.
ratePrecision	number	4	Decimals for the raw rate.
fallback	string	"—"	Shown if a code isn't in the snapshot.

minimumFractionDigits, maximumFractionDigits, currencyDisplay, and locale are forwarded to Intl.NumberFormat.

Reading the snapshot directly

The snapshot is registered as global plugin data:

import { usePluginData } from "@docusaurus/useGlobalData";

const snapshot = usePluginData("docusaurus-plugin-unirate");
// { base, rates, currencies, vatRates?, fetchedAt }

It's also written to unirate-snapshot.json via createData, so route/theme modules can import it statically.

Runtime helpers

import { convertCurrency, getRate, formatCurrency } from "docusaurus-plugin-unirate";

const snap = { base: "USD", rates: { USD: 1, EUR: 0.925 }, currencies: ["USD", "EUR"], fetchedAt: null };
formatCurrency(convertCurrency(snap, 100, "USD", "EUR"), "EUR"); // → "€92.50"

How the build works

The plugin's loadContent hook calls /api/rates?from=<baseCurrency> (plus /api/currencies and, with includeVat, /api/vat/rates) once per build. In contentLoaded, the resulting snapshot is published two ways: setGlobalData(snapshot) (readable with useGlobalData/usePluginData) and createData("unirate-snapshot.json", …) (importable JSON).

Cross-pair rates are derived: rate(from → to) = rate(base → to) / rate(base → from), so a USD-keyed snapshot can convert EUR → GBP without an extra fetch.

Error handling

The bundled client maps HTTP status codes to typed errors, all extending UniRateError:

Status	Error
400	InvalidDateError
401	AuthenticationError
403	APIError (Pro subscription required)
404	InvalidCurrencyError
429	RateLimitError
503 / other	APIError
network / transport	UniRateError

By default a hard error fails the build; set failOnFetchError: false to warn and ship an empty snapshot instead.

Other UniRate clients

UniRate ships official client libraries and framework integrations across the ecosystem, all maintained under the UniRate-API org.

• Languages: Python · Node.js / TypeScript · Go · Rust · Java · Ruby · PHP · .NET · Swift
• Static-site generators: Astro · Eleventy · Hugo · Docusaurus
• Web frameworks: NestJS · FastAPI · Flask · React · tRPC
• Data / orchestration: Airflow · dbt · LangChain

Get a free API key at unirateapi.com.

License

MIT