next-axis — Next.js-native fetch with Axios-level DX

Axios DX without losing Next.js caching. A tiny, zero-dependency HTTP client built on platform fetch that preserves next: { revalidate, tags }, request memoization, and Edge compatibility—while giving you the ergonomics you actually want.

Why this exists

You love Next.js RSC, Server Actions, ISR, tag revalidation… but real apps still call external APIs.

• Use Axios and you opt out of Next’s server fetch cache/memoization and tag revalidation.
• Use native fetch and you’re stuck sprinkling if (!res.ok) throw … everywhere, wiring AbortController by hand, and duplicating error handling.

next-axis is a purpose-built, Next-aware wrapper that keeps platform fetch semantics intact and adds a thin layer of DX:

• Axios-style methods: .get/.post/.put/.patch/.delete/.head/.options
• Clean errors: auto-reject on non-2xx with error.response.data
• Interceptors: request & response (auth headers, logging, metrics)
• Base URL helpers
• Timeout via AbortController
• 100% Edge/Workers safe, zero dependencies
• Full RequestInit pass-through (including next: { revalidate, tags }, cache, signal, credentials)

Not “just another wrapper.” It’s designed specifically for Next.js server/RSC/Route Handlers where fetch is the framework boundary.

Install

npm i next-axis
# or
pnpm add next-axis
# or
yarn add next-axis

Quick start

import http from "next-axis";

// 1) Optional: set a base URL
http.setBaseURL(process.env.NEXT_PUBLIC_API_URL!);

// 2) Minimal auth & cache discipline
http.interceptors.request.use((cfg) => {
  const m = (cfg.method ?? "GET").toUpperCase();
  if (m !== "GET") {
    cfg.withCredentials = true; // cookie auth
    (cfg.headers as any) = {
      ...(cfg.headers ?? {}),
      "X-CSRF-Token": getCsrfToken(),
    };
    cfg.cache = "no-store"; // never cache mutations
  }
  return cfg;
});

// 3) Call it — resolves to `data`
const posts = await http.get<Post[]>("/posts", {
  next: { revalidate: 300, tags: ["posts"] }, // ✅ Next caching + tags preserved
});

Error handling (Axios-style)

import type { HttpError } from "next-axis";

try {
  await http.get("/missing");
} catch (e) {
  const err = e as HttpError;
  console.log(err.status);           // e.g., 404
  console.log(err.response?.data);   // parsed body if JSON/text
}

Route Handler example (server caching + invalidation)

// app/api/posts/route.ts
import http from "next-axis";

export async function GET() {
  const posts = await http.get<Post[]>("https://api.example.com/posts", {
    next: { revalidate: 300, tags: ["posts"] },
  });
  return Response.json(posts);
}

Later, invalidate everywhere tagged "posts":

// app/api/revalidate/route.ts
import { revalidateTag } from "next/cache";

export async function POST() {
  revalidateTag("posts");
  return Response.json({ ok: true });
}

Why pick next-axis over other clients?

| Concern | next-axis | Axios | Ky / ofetch / wretch | | ----------------------------------------------------- | ------------------------------ | ---------------------- | ------------------------------------------------ | | Next server cache (revalidate, tags, memoization) | ✅ Preserved (pass-through) | ❌ Not integrated | ✅ Possible if you forward next (often untyped) | | Edge runtime (no Node APIs) | ✅ | ⚠️ Needs fetch adapter | ✅ | | Errors (auto throw + response.data) | ✅ | ✅ | ✅ (varies per lib) | | Interceptors | ✅ | ✅ | ✅ (hooks/middlewares) | | Size / deps | Zero deps, tiny | Heavier | Small | | DX focus | Axios-style | Axios | Different APIs |

next-axis is the sweet spot if your priority is Next features first, Axios-level DX second.

API

Methods (all resolve to data)

http.get<T>(url, config?)
http.post<T, B>(url, body?, config?)
http.put<T, B>(url, body?, config?)
http.patch<T, B>(url, body?, config?)
http.delete<T>(url, config?)
http.head<T>(url, config?)
http.options<T>(url, config?)
http.request<T>(config) // { url, method, ... }

Configuration (TypeScript)

export type NextCache = { revalidate?: number | false; tags?: string[] };

export type RequestConfig<D = any> = RequestInit & {
  url?: string;
  method?: "GET" | "POST" | "PUT" | "PATCH" | "DELETE" | "HEAD" | "OPTIONS";
  baseURL?: string;
  headers?: HeadersInit;
  data?: D;           // auto-JSON if plain object
  timeout?: number;   // ms, AbortController
  withCredentials?: boolean; // → credentials:'include'
  next?: NextCache;   // passed straight to fetch (server only)
};

Interceptors

// Request (FIFO)
const reqId = http.interceptors.request.use((cfg) => {
  // mutate cfg: add Authorization, trace headers, etc.
  return cfg;
});

// Response (FIFO)
const resId = http.interceptors.response.use((resp) => {
  // inspect/transform resp if needed; must return it
  return resp;
});

// Remove later
http.interceptors.request.eject(reqId);
http.interceptors.response.eject(resId);

Runtime helpers

http.setBaseURL("https://api.example.com");
http.setHeader("X-App", "my-app");
http.removeHeader("X-App");

Best practices (Next.js)

• Cache only idempotent GETs. Use next: { revalidate: N, tags: [...] } or cache: 'force-cache'.
• Never cache per-user data. For authenticated/user-scoped responses, set cache: 'no-store' (or revalidate: 0).
• Keep GET headers stable. Don’t add non-deterministic headers (timestamps, random IDs) in request interceptors for cached requests.
• Client components: next options are ignored in the browser—server caching lives on the server.

FAQ

Why not just Axios with the fetch adapter? You still won’t get Next’s server fetch features (revalidate/tags/memoization). next-axis embraces platform fetch to keep those benefits.

How is this different from Ky/ofetch? Those are great! next-axis is laser-focused on Axios-style DX + explicit Next cache support with zero extra defaults that might change cache keys. If you already use Ky/ofetch, make sure you forward next and avoid mutating GET headers.

Upload/download progress? Not included (to stay tiny). If you need progress, add a browser-only XHR upload helper or a Node streaming path for downloads.

Install size & runtime

• Zero dependencies
• Works in Node 18+, modern browsers, and Next.js Edge/Node runtimes.

License

MIT © Kehinde Oke