재밌는 ky 라이브러리

houndhollis·2026년 1월 31일

최근 리액트 과제를 진행하던 중, ky 라이브러리를 한 번 사용해보고자 하여 작업을 진행하게 되었습니다.
생각보다 괜찮은 점이 많아, 이번 기회에 간단하게 정리해보고자 합니다.

ky vs axios 간단 비교

항목	ky	axios
기반	Fetch API	XMLHttpRequest
번들 사이즈	매우 작음	상대적으로 큼
HTTP 에러 처리	4xx/5xx 자동 throw	수동 처리
인터셉트 방식	hook	interceptor
SSR / Edge	유리	설정 필요

ky 보러가기

ky를 선택한 이유

axios는 오랫동안 사실상 표준처럼 사용돼 왔지만, 이번에 사용한 Vite 환경에서는
Fetch 기반의 ky도 잘 어울릴 것 같다고 느꼈습니다.

특히 추후 Next.js 환경에서 번들 사이즈, 웹 표준 API 사용, 명확한 에러 흐름을 중요하게 보게 되면서
이참에 ky를 한 번 제대로 사용해보자는 생각으로 선택하게 되었습니다.

이번 글에서는 실제로 ky를 사용해 공통 API Client를 구성하고, 실제 API 레이어에서 어떻게 사용했는지 정리해보겠습니다.

공통 API Client 구성

API를 호출할 때마다 토큰을 붙이거나, 에러 코드를 분기 처리하는 로직이 여기저기 흩어지면 유지보수가 어려워지기 마련입니다.

그래서 먼저 ky.create를 사용해 모든 요청의 진입점이 되는 base client를 구성했습니다.

import ky from 'ky';
import Cookies from 'js-cookie';
import { FAILURE_CODES, type BaseResponseType } from '../types';
import { removeToken } from '@/shared/utils/auth';

export const baseApiClient = ky.create({
  prefixUrl: '/api',
  hooks: {
    beforeRequest: [
      (request) => {
        const token = Cookies.get('accessToken');

        if (token) {
          request.headers.set('Authorization', `Bearer ${token}`);
        }
      },
    ],
    afterResponse: [
      async (_request, _options, response) => {
        if (response.ok) {
          return;
        }

        const res = (await response.json()) as BaseResponseType<{}>;

        // 인증 만료 시 토큰 제거
        if (res.code === FAILURE_CODES.UNAUTHORIZED) {
          return removeToken();
        }

        throw {
          code: res.code,
          data: res.data,
          message: res.message,
        };
      },
    ],
  },
});

물론 해당 baseApiClient에서는 많은 내용을 다루진 않지만 중요한 포인트로 뽑는다면,

첫 번째는 beforeRequest hook입니다.
요청이 나가기 직전에 실행되기 때문에, 쿠키에 저장된 토큰을 읽어 Authorization 헤더에 자동으로 주입할 수 있습니다. 이 덕분에 이후 API 호출부에서는 인증 관련 코드를 전혀 신경 쓰지 않아도 됩니다.

두 번째는 afterResponse hook입니다.
ky는 기본적으로 4xx, 5xx 응답을 에러로 판단하지만,
여기서는 한 단계 더 나아가 서버에서 내려주는 공통 응답 구조의 code 값을 기준으로 에러를 처리했습니다.
인증이 만료된 경우에는 토큰을 제거하고, 그 외의 경우에는 도메인 에러 객체를 throw하도록 구성했습니다.

HTTP 메서드 래핑

baseApiClient 위에 바로 ky를 사용해도 되지만, 응답 타입과 호출 방식을 통일하기 위해 한 번 더 래핑을 했습니다.

import { baseApiClient } from './baseClient';
import type { BaseResponseType } from '../types';
import type { Options } from 'ky';

export const client = {
  get: async <T>(url: string, options?: Options) =>
    baseApiClient.get(url, options).json<BaseResponseType<T>>(),

  post: async <T>(url: string, options?: Options) =>
    baseApiClient.post(url, options).json<BaseResponseType<T>>(),

  put: async <T>(url: string, options?: Options) =>
    baseApiClient.put(url, options).json<BaseResponseType<T>>(),

  patch: async <T>(url: string, options?: Options) =>
    baseApiClient.patch(url, options).json<BaseResponseType<T>>(),

  delete: async <T>(url: string, options?: Options) =>
    baseApiClient.delete(url, options).json<BaseResponseType<T>>(),
};

이 구조의 목적은 단순합니다.
모든 API 응답은 BaseResponseType<T> 형태로만 받는다는 규칙을 강제하는 것입니다.

API 사용부에서는 HTTP 구현이나 파싱 로직을 전혀 알 필요가 없고,
오직 "어떤 데이터를 요청하고 어떤 타입을 받는지만" 신경 쓰면 됩니다.

실제 사용 예시

import { client } from '../client/apiClient';
import type { AuthLoginResponse } from './types';

// ------------------ 로그인 API -----------------------
export const loginWithEmail = async (email: string) => {
  const res = await client.post<AuthLoginResponse>('auth/login', {
    searchParams: {
      email,
    },
  });

  return res;
};