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