Tutorial/Next.js와 TypeScript

Next.js와 TypeScript에서 환율 사용하기

Next.js Server Component에서 실시간 환율을 가져오고, API 키를 클라이언트에 노출하지 않으며, 원본 데이터가 마지막으로 갱신된 시점을 숨기지 않고 응답을 캐시하는 방법을 설명합니다.

MMexchangerate.dev·Jul 17, 2026·6분 읽기

exchangerate.dev는 Server Component 또는 Route Handler에서 호출하고, 키가 포함된 브라우저 코드에서는 절대 호출하지 마세요. Next.js는 업스트림 요청을 60초마다 재검증할 수 있으며, 응답 필드 source, market_session, data_updated_at은 캐시된 값이 실제로 무엇을 의미하는지 UI에 알려줍니다.

Key points
EXCHANGERATE_API_KEY는 서버 전용 환경 변수에 보관하세요. NEXT_PUBLIC_ 접두사를 절대 붙이지 마세요.
Next.js 서버 측 fetchnext: { revalidate: 60 }을 사용해 페이지 조회마다 업스트림 요청이 발생하지 않도록 하세요.
응답의 timestamp를 신선도의 증거로 삼지 말고, data_updated_at을 표시하세요.
표시와 분석에는 인디케이티브 환율을 사용하고, 체결 가능한 정산 금액은 결제 제공업체가 결정하도록 하세요.

서버 측에서 가져오기

Server Component는 브라우저 밖에서 실행되므로 비공개 환경 변수를 읽을 수 있습니다. 아래 예제는 USD 대비 EUR과 GBP만 요청하고, HTTP 상태를 확인한 뒤 타입이 지정된 JSON을 페이지로 반환합니다.

typescript · app/page.tsxcopy
type LatestRates = {
  base: string;
  source: "live" | "ecb_daily" | "fred_daily";
  market_session: string;
  data_updated_at: string;
  rates: Record<string, number>;
};

async function getRates(): Promise<LatestRates> {
  const apiKey = process.env.EXCHANGERATE_API_KEY;
  if (!apiKey) throw new Error("EXCHANGERATE_API_KEY is missing");

  const response = await fetch(
    "https://api.exchangerate.dev/v1/latest/USD?symbols=EUR,GBP",
    {
      headers: { Authorization: `Bearer ${apiKey}` },
      next: { revalidate: 60 },
    },
  );

  if (!response.ok) {
    throw new Error(`FX request failed: ${response.status}`);
  }

  return response.json() as Promise<LatestRates>;
}

export default async function Page() {
  const fx = await getRates();

  return (
    <main>
      <p>1 USD = {fx.rates.EUR} EUR</p>
      <small>
        {fx.source} · {fx.market_session} · updated {fx.data_updated_at}
      </small>
    </main>
  );
}

요청을 캐시하고 관측 시각을 보존하기

next: { revalidate: 60 }은 업스트림 요청의 캐시 수명을 최대 60초로 제한합니다. 이는 페이지 조회마다 중복 호출이 발생하는 것을 줄여주지만, 일별 참조 환율을 장중 실시간 환율로 만들어 주지는 않으므로 값 옆에 source, market_session, data_updated_at을 함께 보관하세요.

키를 노출하지 마세요
NEXT_PUBLIC_ 접두사가 붙은 환경 변수는 브라우저 번들에 포함될 수 있습니다. 이 비밀 값은 EXCHANGERATE_API_KEY로 이름 짓고 서버 코드에서만 읽으세요. 익명 호출은 간단한 테스트에는 괜찮지만, 프로덕션 코드에서는 키를 사용해야 합니다.

표시 통화와 정산 통화를 분리하기

스토어프론트는 인디케이티브 환율로 대략적인 현지 가격을 표시할 수 있습니다. 수수료, 스프레드, 반올림, 정산 시점에 따라 체결 금액이 달라질 수 있으므로 최종 청구 금액은 결제 제공업체 또는 거래 체결 기관에서 가져와야 합니다.

  • API 키를 서버에 보관하세요.
  • 401이나 429 오류가 아니라 성공한 응답만 캐시하세요.
  • 신선도가 중요할 때는 환율 출처와 관측 시각을 표시하세요.
  • 원래 상품 가격과 통화를 정산의 근거로 유지하세요.
MM
exchangerate.dev
FX 데이터를 다루는 개발자를 위한 연동 가이드.

Keep reading

TutorialJavaScript와 Node.js에서의 통화 변환Read Referencesource와 market_session 읽는 법Read Guide인디케이티브 환율과 체결 가능 환율Read