@unirate/eleventy

Eleventy plugin for UniRate — fetches a currency exchange rate snapshot at build time, exposes it through unirate global data, and ships currency / rate / convert shortcodes and filters.

• 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 snapshot stays small.
• Works in Nunjucks and Liquid (Eleventy's default engines).

Install

npm install @unirate/eleventy

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

Configure

// eleventy.config.mjs
import unirate from "@unirate/eleventy";

export default function (eleventyConfig) {
  eleventyConfig.addPlugin(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 bundled 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 templates fall back gracefully. | | shortcodePrefix | string | "" | Namespace prefix. Set to e.g. "unirate" to register shortcodes/filters as unirateCurrency, unirateRate, unirateConvert. |

Shortcodes

{# Convert and format an amount #}
<p>Total: {% currency 100, "USD", "EUR" %}</p>
<p>JPY: {% currency 1234.5, "USD", "JPY", { minimumFractionDigits: 0 } %}</p>
<p>Code style: {% currency 100, "USD", "EUR", { currencyDisplay: "code" } %}</p>

{# Just the rate, fixed precision #}
<p>USD/EUR: {% rate "USD", "EUR" %}</p>
<p>Cross-pair: {% rate "EUR", "GBP", 6 %}</p>

{# Just the converted amount (no currency formatting) #}
<p>50 USD ≈ {% convert 50, "USD", "GBP" %} GBP</p>

Filters

The same three operations are available as filters for inline use:

<p>Total: {{ 100 | currency("USD", "EUR") }}</p>
<p>Rate: {{ "USD" | rate("EUR") }}</p>
<p>Converted: {{ 50 | convert("USD", "GBP") }}</p>

Liquid uses the same names:

{{ 100 | currency: "USD", "EUR" }}

Global data

The full snapshot is exposed as unirate:

<p>Base: {{ unirate.base }}</p>
<p>EUR rate: {{ unirate.rates.EUR }}</p>
<footer>Rates as of {{ unirate.fetchedAt }}</footer>

Use the helpers directly

import { convertCurrency, getRate, formatCurrency } from "@unirate/eleventy/runtime";

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

How the build works

addGlobalData("unirate", ...) registers an async thunk that fetches /api/rates?from=<baseCurrency>[&to=...] once before any template is rendered. The result is cached, then shared with the shortcode and filter implementations, so every conversion in every template reads from the same in-memory snapshot.

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

License

MIT