hugo-unirate

Hugo Module that renders live currency conversions and exchange rates inside your site at build time, backed by the UniRate API. 170+ fiat currencies and crypto, with a free tier covering live conversion and supported-currencies listing.

100 USD = {{< currency from="USD" to="EUR" amount="100" >}}
USD/EUR rate: {{< rate from="USD" to="EUR" >}}

renders to:

100 USD = 92.43 EUR
USD/EUR rate: 0.9243

Install

Requires Hugo 0.141.0+ (uses the try keyword) and Go installed (Hugo modules use Go's module resolver — no Go code is shipped).

In your site's hugo.toml (or config.toml):

[module]
  [[module.imports]]
    path = "github.com/UniRate-API/hugo-unirate"

[params]
  [params.unirate]
    apiKey = "YOUR_UNIRATE_API_KEY"

Then:

hugo mod get github.com/UniRate-API/hugo-unirate

Get a free API key at https://unirateapi.com.

Avoid committing your key

Set the key via env var instead — Hugo reads HUGO_PARAMS_UNIRATE_APIKEY into site.Params.unirate.apiKey automatically:

export HUGO_PARAMS_UNIRATE_APIKEY=your_key
hugo --minify

Shortcodes

currency — convert an amount

{{< currency from="USD" to="EUR" amount="100" >}}    → 92.43 EUR
{{< currency USD GBP 50 >}}                          → 39.50 GBP   (positional)
{{< currency from="USD" to="JPY" amount="1" format="¥%.0f" >}}  → ¥147

arg	required	default	notes
from	no	USD	source currency code
to	yes	—	target currency code
amount	no	1	numeric amount to convert
format	no	%.2f %s	Go printf format; receives (value, code)

rate — fetch the raw exchange rate

{{< rate from="USD" to="EUR" >}}                     → 0.9243
{{< rate USD JPY format="%.2f" >}}                   → 147.32

arg	required	default	notes
from	no	USD	source currency code
to	yes	—	target currency code
format	no	%.4f	Go printf format; receives float

Partials (use from your own templates)

Call directly from layouts when you need the numeric value, not formatted text:

{{ $eur := partialCached "unirate/convert.html" (dict
    "from" "USD" "to" "EUR" "amount" .Params.priceUSD
) .Params.priceUSD }}
<p>Price in EUR: <strong>{{ printf "€%.2f" $eur }}</strong></p>

Available partials:

partial	returns	context keys
unirate/convert.html	float	from, to, amount
unirate/rate.html	float	from, to
unirate/currencies.html	[]string	(none)

All three use resources.GetRemote, so Hugo's built-in HTTP cache dedupes identical requests within a build. Wrap calls in partialCached to dedupe across multiple invocations with the same arguments.

How rates are fetched

Each unique (endpoint, params) combination triggers one HTTPS call to https://api.unirateapi.com during hugo build. Responses go through Hugo's resources.GetRemote cache (default lifetime: until you run hugo --gc). Failed requests log a WARN and render the value as 0 so your build never breaks because of a transient network blip.

To force fresh rates on every build (e.g. in CI on a schedule), pass a cacheBust value into the partial:

{{ partial "unirate/_api.html" (dict
    "endpoint" "/api/convert"
    "params" (dict "from" "USD" "to" "EUR" "amount" "100")
    "cacheBust" now.Unix
) }}

Configuration reference

key	default	notes
params.unirate.apiKey	(empty — required)	get one at unirateapi.com
params.unirate.apiBaseUrl	https://api.unirateapi.com	override for self-hosted/mock

Both can be set via HUGO_PARAMS_UNIRATE_APIKEY / HUGO_PARAMS_UNIRATE_APIBASEURL.

Free vs Pro

endpoint used by	free tier	Pro tier
currency, rate, currencies partial	yes	yes
historical rates (not yet exposed)	no	yes

Pro endpoints (/api/historical/*, commodities) return HTTP 403 on the free tier and would render as 0 with a WARN. They aren't wired up here — open an issue if you want them.

Related UniRate clients

If you need rates outside Hugo, there are first-party clients for Python, Node, Go, Rust, Ruby, PHP, Swift, Java, and .NET.

UniRate ecosystem

UniRate ships official integrations for 40+ ecosystems, all maintained under the UniRate-API org.

Core clients (9 languages) Python · Node.js / TypeScript · Go · Rust · Java · Ruby · PHP · .NET · Swift

JavaScript / TypeScript React · Next.js · Remix · SvelteKit · Vue · Angular · Nuxt · NestJS · tRPC

Static-site generators Astro · Eleventy · Hugo · Jekyll

CMS & e-commerce Wagtail · WordPress · WooCommerce · Drupal · Strapi · Medusa · Symfony · Laravel · Directus

Data, AI & backend LangChain (Python) · LangChain.js · FastAPI · Flask · Django REST Framework · Apache Airflow · dbt

Platform & tools MCP server · CLI · Cloudflare Workers · Home Assistant · n8n · Google Sheets · VS Code · Obsidian

Money library bridges money gem (Ruby) · NodaMoney (.NET)

Get a free API key at unirateapi.com.

License

MIT — see LICENSE.