@unirate/svelte

Plain Svelte store integration for the UniRate currency exchange API.

createUniRate() gives you reactive readable stores — rate, rates, conversion, currencies, vatRates — each carrying { data, error, loading } with a refresh() method. Works with Svelte 4 and Svelte 5. Zero runtime dependencies (native fetch + svelte/store).

Framework-agnostic: this is the plain-Svelte-stores package. If you're on SvelteKit and want server load helpers, a geo hook, and an API-route proxy, use @unirate/sveltekit instead.

Install

npm install @unirate/svelte svelte

Quick start

# .env — get a free key at https://unirateapi.com
UNIRATE_API_KEY=your-api-key-here

<script>
  import { createUniRate } from '@unirate/svelte';

  const uni = createUniRate({ apiKey: import.meta.env.VITE_UNIRATE_API_KEY });

  const rate = uni.rate('USD', 'EUR');
  const price = uni.conversion('USD', 'EUR', 99.99);
  const codes = uni.currencies();
</script>

{#if $rate.loading}
  Loading…
{:else if $rate.error}
  {$rate.error.message}
{:else}
  <p>1 USD = {$rate.data} EUR</p>
{/if}

<button on:click={rate.refresh}>Refresh</button>

Never ship a real API key to the browser in production. Proxy UniRate through your own backend and point the client's baseUrl at your proxy, or fetch on the server and pass values down.

API

createUniRate(options)

Builds one UniRateClient and returns store constructors bound to it.

const uni = createUniRate({
  apiKey: 'your-key',      // required
  baseUrl?: string,        // default https://api.unirateapi.com
  fetch?: typeof fetch,    // inject a custom fetch (e.g. SvelteKit's load fetch)
  timeoutMs?: number,      // default 30000
  userAgent?: string,
});

Returns:

| Member | Returns | Notes | |---|---|---| | uni.client | UniRateClient | The underlying imperative client. | | uni.rate(from, to) | QueryStore<number> | Single exchange rate. | | uni.rates(from) | QueryStore<Record<string, number>> | All rates for from. | | uni.conversion(from, to, amount) | QueryStore<number> | amount of from in to. | | uni.currencies() | QueryStore<string[]> | Supported currency codes. | | uni.vatRates() | QueryStore<VATRatesAll> | All countries. | | uni.vatRates(country) | QueryStore<VATRateOne> | One country (ISO-3166 alpha-2). |

QueryStore<T>

A Svelte readable of:

interface QueryState<T> {
  data: T | undefined;      // settled value, or undefined until first success
  error: Error | undefined; // last error, or undefined while healthy
  loading: boolean;         // true until the first request settles; true again during refresh()
}

plus:

store.refresh(); // abort any in-flight request and re-fetch (no-op with no subscribers)

The request fires lazily on the first subscription and is torn down when the last subscriber leaves — the standard Svelte store lifecycle. An in-flight request is aborted whenever refresh() runs again or the store stops, so a stale response can never overwrite a newer one. During a refresh() the previously settled data stays put while loading flips to true.

Imperative client

Everything is also available directly on uni.client (or import UniRateClient and construct it yourself):

import { UniRateClient } from '@unirate/svelte/client';

const client = new UniRateClient({ apiKey: 'your-key' });
const rate = await client.getRate('USD', 'EUR');        // number
const map = await client.getRate('USD');                // Record<string, number>
const eur = await client.convert('EUR', 100, 'USD');    // number
const codes = await client.listCurrencies();            // string[]
const vat = await client.getVatRates('DE');             // { country, vat_data }

Historical/timeseries methods exist for parity but require a UniRate Pro subscription and return 403 (ProRequiredError) on the free tier.

Error handling

Errors are mapped to typed subclasses of UniRateError, surfaced through store.error (or thrown by the client):

| HTTP | Error | | |---|---|---| | 400 | InvalidRequestError | Invalid request parameters | | 401 | AuthenticationError | Missing or invalid API key | | 403 | ProRequiredError | Endpoint requires a Pro subscription | | 404 | InvalidCurrencyError | Currency not found or no data available | | 429 | RateLimitError | Rate limit exceeded | | 503 / other | UniRateError | carries .status and .body | | network | UniRateError | wraps the underlying transport error |

{#if $rate.error}
  {#if $rate.error.name === 'RateLimitError'}
    Slow down — try again in a moment.
  {:else}
    {$rate.error.message}
  {/if}
{/if}

Building

This package is pure TypeScript stores — there are no .svelte component files to compile — so it builds with plain tsc:

npm run build     # tsc -p tsconfig.build.json → dist/ (ESM + .d.ts)

Related

• @unirate/sveltekit — SvelteKit server helpers, hooks, and components
• @unirate/react — React hooks
• @unirate/vue — Vue 3 composables
• unirate-api — the core Node client

License

MIT © Unirate Team