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