http-clients

HTTP Clients Core Knowledge

Full Reference: See advanced.md for token refresh flow, retry with exponential backoff, request cancellation, and type-safe API client patterns.

Deep Knowledge: Use mcp__documentation__fetch_docs with technology: http-clients for comprehensive documentation.

Axios Setup

import axios, { AxiosError, InternalAxiosRequestConfig } from 'axios';

const api = axios.create({
  baseURL: process.env.NEXT_PUBLIC_API_URL,
  timeout: 10000,
  headers: { 'Content-Type': 'application/json' },
});

// Request interceptor - add auth token
api.interceptors.request.use(
  (config: InternalAxiosRequestConfig) => {
    const token = localStorage.getItem('accessToken');
    if (token) {
      config.headers.Authorization = `Bearer ${token}`;
    }
    return config;
  },
  (error) => Promise.reject(error)
);

// Response interceptor - handle errors
api.interceptors.response.use(
  (response) => response,
  (error: AxiosError) => {
    if (error.response?.status === 401) {
      window.location.href = '/login';
    }
    return Promise.reject(error);
  }
);

Fetch API Wrapper

class ApiError extends Error {
  constructor(public status: number, public statusText: string, public data?: unknown) {
    super(`${status}: ${statusText}`);
  }
}

async function fetchWithTimeout(url: string, options: RequestInit & { timeout?: number } = {}): Promise<Response> {
  const { timeout = 10000, ...fetchOptions } = options;
  const controller = new AbortController();
  const timeoutId = setTimeout(() => controller.abort(), timeout);

  try {
    return await fetch(url, { ...fetchOptions, signal: controller.signal });
  } finally {
    clearTimeout(timeoutId);
  }
}

export async function apiFetch<T>(endpoint: string, options: RequestInit = {}): Promise<T> {
  const token = localStorage.getItem('accessToken');
  const headers: HeadersInit = {
    'Content-Type': 'application/json',
    ...(token && { Authorization: `Bearer ${token}` }),
  };

  const response = await fetchWithTimeout(`${API_URL}${endpoint}`, { ...options, headers });

  if (!response.ok) {
    throw new ApiError(response.status, response.statusText);
  }

  return response.json();
}

ky (Modern Fetch Wrapper)

import ky from 'ky';

const api = ky.create({
  prefixUrl: process.env.NEXT_PUBLIC_API_URL,
  timeout: 10000,
  retry: {
    limit: 2,
    methods: ['get', 'put', 'delete'],
    statusCodes: [408, 429, 500, 502, 503, 504],
  },
  hooks: {
    beforeRequest: [
      (request) => {
        const token = localStorage.getItem('accessToken');
        if (token) {
          request.headers.set('Authorization', `Bearer ${token}`);
        }
      },
    ],
  },
});

// Usage
const users = await api.get('users').json<User[]>();
const user = await api.post('users', { json: newUser }).json<User>();

ofetch (Universal Fetch)

import { ofetch } from 'ofetch';

const api = ofetch.create({
  baseURL: process.env.NUXT_PUBLIC_API_URL,
  retry: 2,
  retryDelay: 500,
  timeout: 10000,

  async onRequest({ options }) {
    const token = localStorage.getItem('accessToken');
    if (token) {
      options.headers = { ...options.headers, Authorization: `Bearer ${token}` };
    }
  },
});

// Works in Node.js and browser
const users = await api<User[]>('/users');

When NOT to Use This Skill

• Axios-specific configuration (use axios skill)
• GraphQL client setup (use graphql-codegen skill)
• tRPC client configuration (use trpc skill)
• WebSocket or Server-Sent Events

Anti-Patterns

Anti-Pattern	Why It's Bad	Solution
No timeout configured	Hanging requests	Set timeout on all clients
Hardcoded API URLs	Environment coupling	Use environment variables
No retry logic	Poor UX on transient failures	Implement exponential backoff
Ignoring token expiration	401 errors	Implement token refresh flow
Not canceling on unmount	Memory leaks	Use AbortController cleanup
Not typing responses	Runtime errors	Use TypeScript generics

Quick Troubleshooting

Issue	Possible Cause	Solution
CORS errors	Server misconfiguration	Configure CORS on backend
401 after some time	Token expired	Implement token refresh
Memory leaks	Not aborting on unmount	Add cleanup in useEffect
Network timeout	Server slow	Increase timeout, add retry
Infinite refresh loop	Refresh returns 401	Exclude refresh from interceptor

Production Checklist

• Base URL via environment
• Request timeout configured
• Auth token interceptor
• Token refresh logic
• Error response handling
• Retry with exponential backoff
• Request cancellation on unmount
• Type-safe API methods

Reference Documentation

• Axios Configuration
• Fetch Patterns
• ky and ofetch