@unirate/next

Next.js App Router integration for the UniRate API — free currency exchange rates, conversion, historical data, and VAT rates.

Zero runtime dependencies. Works with Next.js 14+ App Router and React 18/19.

Features

• Async RSC components — <Price /> and <ExchangeRate /> render exchange data server-side with zero client JS
• Server helpers — getRate(), convert(), listCurrencies() with React cache() deduplication
• Currency middleware — auto-detect visitor currency from geo/locale and set it via header + cookie
• Route handler — proxy UniRate API calls through your app to keep the API key server-side
• Next.js Data Cache — pass revalidate to control ISR caching out of the box

Install

npm install @unirate/next

Set your API key (get one free at unirateapi.com):

# .env.local
UNIRATE_API_KEY=your_api_key_here

Quick start

Server Components

// app/page.tsx
import { Price, ExchangeRate, getRate, convert } from '@unirate/next';

export default async function Page() {
  // Use components — they fetch at render time, zero client JS
  return (
    <div>
      <p>Price: <Price amount={99.99} from="USD" to="EUR" /></p>
      <p>Rate: <ExchangeRate from="USD" to="EUR" /></p>
    </div>
  );
}

Server-side data fetching

import { getRate, convert, listCurrencies, createUniRate } from '@unirate/next';

// Top-level functions use UNIRATE_API_KEY from env
const rate = await getRate('USD', 'EUR');           // 0.92
const result = await convert('USD', 'EUR', 100);    // 92.50
const currencies = await listCurrencies();          // ['USD', 'EUR', ...]

// Or create a configured instance with custom options
const unirate = createUniRate({
  apiKey: 'custom-key',        // override env var
  revalidate: 3600,            // ISR: revalidate every hour
});
const rate2 = await unirate.getRate('GBP', 'JPY');

Currency middleware

Auto-detect visitor currency from Vercel/Cloudflare geo headers or Accept-Language:

// middleware.ts
import { createCurrencyMiddleware } from '@unirate/next/middleware';

export const middleware = createCurrencyMiddleware({
  defaultCurrency: 'USD',
});

export const config = {
  matcher: ['/((?!_next/static|_next/image|favicon.ico).*)'],
};

Then read the detected currency in any Server Component:

import { headers } from 'next/headers';

export default async function Page() {
  const h = await headers();
  const currency = h.get('x-unirate-currency') ?? 'USD';
  return <Price amount={49.99} from="USD" to={currency} />;
}

Route handler (API proxy)

Keep your API key server-side by proxying through a Route Handler:

// app/api/unirate/route.ts
import { createUniRateHandler } from '@unirate/next/route';

const handler = createUniRateHandler();
export { handler as GET };

Then call from client components:

// Client-side fetch (no API key exposed)
const res = await fetch('/api/unirate?path=/api/rates&from=USD&to=EUR');
const { rate } = await res.json();

Components

<Price />

Async Server Component that converts an amount and renders it formatted.

Prop	Type	Default	Description
amount	number	—	Amount to convert
from	string	"USD"	Source currency
to	string	—	Target currency
decimals	number	2	Fraction digits
locale	string	runtime	BCP-47 locale for formatting

<ExchangeRate />

Async Server Component that renders a bare exchange rate.

Prop	Type	Default	Description
from	string	—	Base currency
to	string	—	Quote currency
decimals	number	4	Fraction digits
locale	string	runtime	BCP-47 locale for formatting

Error handling

All methods throw typed errors inheriting from UniRateError:

Error	HTTP	Meaning
AuthenticationError	401	Missing or invalid API key
ProRequiredError	403	Endpoint requires Pro subscription
InvalidCurrencyError	404	Currency not found
InvalidRequestError	400	Bad parameters
RateLimitError	429	Rate limit exceeded

Rate limits

The free tier allows 1,000 requests/month. Historical and time-series endpoints require a Pro subscription. See the API docs for details.

Related packages

Package	Description
@unirate/react	React hooks + client components
@unirate/nestjs	NestJS module
@unirate/astro	Astro integration
@unirate/eleventy	Eleventy plugin
trpc-unirate	tRPC v11 router
unirate-api	Standalone Node.js client

License

MIT