gatsby-source-unirate

Gatsby source plugin for UniRate — sources a build-time currency exchange-rate snapshot and the list of supported currencies from the UniRate API into your Gatsby GraphQL layer.

• Creates UniRateExchangeRate nodes (one per target currency) and UniRateCurrency nodes (one per supported currency code).
• Rates resolve at build time, so pages ship static values — no client-side API key, no runtime fetch.
• Zero runtime dependencies (uses native fetch, Node 18+).
• Full UniRate error mapping surfaced through Gatsby's reporter so build failures are actionable (401 key issues, 429 rate limits, 503, etc.).

Install

npm install gatsby-source-unirate

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

gatsby (>=5.0.0) is a peer dependency; you already have it in a Gatsby project.

Configure

// gatsby-config.js
require("dotenv").config();

module.exports = {
  plugins: [
    {
      resolve: "gatsby-source-unirate",
      options: {
        apiKey: process.env.UNIRATE_API_KEY,
        baseCurrency: "USD",
        currencies: ["EUR", "GBP", "JPY", "CAD", "AUD"],
      },
    },
  ],
};

Keep the key in an environment variable (e.g. via dotenv) so it never lands in your repository.

Options

Option	Type	Default	Description
apiKey	string	— (required)	UniRate API key.
baseCurrency	string	"USD"	Base currency the rate snapshot is keyed against.
currencies	string[]	all UniRate currencies for the base	Optional allowlist of target currency codes.
apiBaseUrl	string	"https://api.unirateapi.com"	API host. Override for self-hosted or testing.
timeoutMs	number	30000	Per-request timeout in milliseconds.

Options are validated by Gatsby via the plugin's pluginOptionsSchema, so a missing apiKey or a malformed option fails fast with a clear message.

Nodes

UniRateExchangeRate

One node per target currency (the base→base identity is skipped).

Field	Type	Description
base	String	Base currency code.
currency	String	Target currency code.
rate	Float	Units of currency per 1 unit of base.
fetchedAt	String	ISO-8601 timestamp of the source run.

UniRateCurrency

One node per currency code UniRate supports.

Field	Type	Description
code	String	Currency code (e.g. "EUR").

Query

# All rates for the configured base currency.
query {
  allUniRateExchangeRate(sort: { currency: ASC }) {
    nodes {
      base
      currency
      rate
      fetchedAt
    }
  }
}

# The supported currency list.
query {
  allUniRateCurrency(sort: { code: ASC }) {
    nodes {
      code
    }
  }
}

See examples/ for a full gatsby-config.js and a set of sample queries.

How it works

At Gatsby's sourceNodes lifecycle step the plugin makes two free-tier UniRate calls:

• GET /api/rates?from=<baseCurrency>[&to=...] — the rate snapshot.
• GET /api/currencies — the supported currency list.

Each rate becomes a UniRateExchangeRate node and each currency a UniRateCurrency node, created with createNode + createNodeId + createContentDigest per Gatsby conventions. Accept: application/json is sent on every request (UniRate returns an HTML 404 without it).

If a fetch fails, the plugin calls reporter.panicOnBuild with the mapped error and HTTP status so the build stops with an actionable message. A missing/invalid apiKey calls reporter.panic before any network call.

Error handling

HTTP status codes map to typed errors (all extend UniRateError):

Status	Error	Meaning
400	InvalidRequestError	Invalid request parameters.
401	AuthenticationError	Missing or invalid API key.
403	APIError	Endpoint requires a UniRate Pro subscription.
404	InvalidCurrencyError	Currency not found or no data available.
429	RateLimitError	Rate limit exceeded.
503	APIError	Service unavailable.
network	UniRateError	Transport failure (wrapped).

Rate limits

The free tier is rate-limited. Because the plugin sources at build time it makes just two requests per build, so it stays comfortably within limits for normal use. Historical and commodity endpoints require a UniRate Pro subscription and are not used by this plugin.

Other UniRate clients

UniRate ships official client libraries and framework integrations across the ecosystem. The repos below are 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 · Gatsby
• Web frameworks: NestJS · FastAPI · Flask · React · tRPC
• Workflow / no-code: n8n · Google Sheets · MCP server

Get a free API key at unirateapi.com.

License

MIT © Unirate Team