Colocate Your API Layer: A Next.js App Router Pattern That Scales

Philip Daniel Oghenetega — Thu, 25 Jun 2026 07:09:07 +0000

Keep your data-fetching logic next to where it's actually used — and watch your codebase stay navigable past 30 feature modules.

I'm a frontend engineer at MTN Nigeria. This pattern emerged from building a production-grade retail POS system serving users, merchants, and admins across multiple regions.

The `services/` folder that ate the codebase

Every frontend project grows a services/ directory. It starts as one file. Then it's ten. Then someone adds merchantService.ts, adminMerchantService.ts, and merchantAdminService.ts, and nobody can tell you the difference without opening all three. You scroll through hundreds of exports hunting for one function, and it's never where you'd expect.

The centralized pattern feels organized right up until your project is large enough to prove it isn't. Once a codebase has 30-plus distinct feature modules — admin canvassers, merchant inventory, logistics, settlements, reporting, locations, compliance — a single services/ folder stops being a map and becomes a maze.

This article walks through the alternative: a colocated API layer, taken from a production retail POS system built on Next.js 15 App Router. The project runs two distinct dashboards — (AdminDashboard) and (MerchantDashboard) — across dozens of independent feature modules. Every module owns its own API calls. Nothing leaks.

What "colocated" actually means

Colocation just means the API functions for a feature live inside that feature's directory, not in a global folder somewhere else. The structure looks like this:

src/app/
├── (AdminDashboard)/
│   ├── admin-merchants/
│   │   ├── api/
│   │   │   └── index.ts        ← merchant API calls
│   │   ├── columns/
│   │   │   └── index.tsx
│   │   ├── components/
│   │   └── page.tsx
│   ├── admin-inventory/
│   │   ├── api/
│   │   │   └── index.ts        ← inventory API calls
│   │   └── page.tsx
│   ├── admin-settlement/
│   │   ├── api/
│   │   │   └── index.ts        ← settlement API calls
│   │   └── page.tsx
│   └── admin-logistics/
│       ├── api/
│       │   └── index.ts        ← logistics API calls
│       └── page.tsx
└── (MerchantDashboard)/
    ├── merchant-inventory/
    │   ├── api/
    │   │   └── index.ts        ← merchant inventory API calls
    │   └── page.tsx
    └── merchant-home/
        ├── api/
        │   └── index.ts        ← dashboard analytics API calls
        └── page.tsx

Each api/index.ts is a plain TypeScript module that exports async functions. No classes, no DI containers, no registries — just functions. This is the same principle that makes App Router route groups work: code that changes together lives together.

The one thing that stays global: a typed Axios instance

Only the HTTP client itself lives globally. Every api/index.ts in the project imports from the same place:

// src/components/Auth/Instance.ts

import axios, {
  AxiosInstance,
  AxiosRequestConfig,
  InternalAxiosRequestConfig,
  AxiosResponse,
  AxiosError,
} from "axios";
import TokenService from "./TokenService";
import { toast } from "sonner";

interface CustomAxiosInstance extends AxiosInstance {
  get<T = any, R = AxiosResponse<T>>(url: string, config?: AxiosRequestConfig): Promise<R>;
  post<T = any, R = AxiosResponse<T>>(url: string, data?: any, config?: AxiosRequestConfig): Promise<R>;
  put<T = any, R = AxiosResponse<T>>(url: string, data?: any, config?: AxiosRequestConfig): Promise<R>;
  patch<T = any, R = AxiosResponse<T>>(url: string, data?: any, config?: AxiosRequestConfig): Promise<R>;
}

const instance: CustomAxiosInstance = axios.create({
  baseURL: process.env.NEXT_PUBLIC_BASE_URL,
  timeout: 36000,
});

The key decision: CustomAxiosInstance re-declares the HTTP method signatures with generics. Every downstream API call then gets full TypeScript inference — the response type flows from the call site all the way to the consuming component, no casting required.

Request interceptor: token injection

instance.interceptors.request.use(
  (config: InternalAxiosRequestConfig): InternalAxiosRequestConfig => {
    const token = TokenService.getLocalAccessToken();
    if (token) {
      config.headers.Authorization = `Bearer ${token}`;
    }
    return config;
  },
  (error) => Promise.reject(error),
);

Every outbound request gets the bearer token attached automatically. No individual API function thinks about auth headers. This is the only kind of logic that belongs in the shared layer: behavior that genuinely applies to every single request.

Response interceptor: centralized error handling

The response interceptor maps every HTTP error the API can return — 400, 401, 403, 404, 405, 408, 409, 412, 429, 500, 502 — to a user-facing toast. The 401 case carries the most weight, because it has to distinguish a real session expiry on a protected route from a legitimate 401 coming back from an auth endpoint like /login or /verify:

const isAuthEndpoint =
  requestUrl.includes("/login") ||
  requestUrl.includes("/otp") ||
  requestUrl.includes("/verify");

if (isAuthEndpoint) {
  return Promise.reject(error); // let the form handle this
}

// session expired on a protected route
TokenService.removeUserAndRedirect();

This is exactly where that logic should live. If each API function handled its own 401, you'd either duplicate the redirect across dozens of files or extract a utility and import it everywhere anyway. The interceptor does it once, invisibly.

Role-aware token management

The app runs three concurrent session types — admin, merchant, and user — and TokenService resolves the right token by reading the current URL path:

// src/components/Auth/TokenService.ts

const ROLE_PREFIXES: Record<SessionRole, string[]> = {
  admin: ["admin", "super_admin"],
  merchant: ["general_manager", "regional_manager", "state_manager"],
  user: ["user", "branch_staff", "customer"],
};

getLocalAccessToken(pathname?: string): string | undefined {
  const role = this.getSessionRoleFromPath(pathname);
  return Cookies.get(`token-${role}`);
}

Tokens live in role-namespaced cookies — token-admin, token-merchant, token-user. When the request interceptor calls getLocalAccessToken(), it derives the cookie key from window.location.pathname. An admin moving through /admin-merchants gets the admin token; a merchant on /merchant-inventory gets the merchant token.

The subtle payoff: the shared Axios instance never needs to know which role is active. TokenService owns that resolution, and the interceptor just calls the method.

The pattern in practice

Here's the merchants API module in full:

// src/app/(AdminDashboard)/admin-merchants/api/index.ts

import axios from "@/components/Auth/Instance";
import { MerchantStatusUpdate, updateStatusType } from "@/types";

export const getMerchants = (
  page: number,
  searchTerm: string,
  activeTab: string,
  startDate?: string,
  endDate?: string
) => {
  return axios
    .get(`merchant/list?page=${page}&limit=10&search=${searchTerm}&status=${activeTab}&startDate=${startDate}&endDate=${endDate}`)
    .then((res) => res.data);
};

export const getSingleMerchant = (id: string) => {
  return axios.get(`merchant/${id}`).then((res) => res.data);
};

export const createMerchants = (value: FormData) => {
  return axios.post("merchant/add", value).then((res) => res.data);
};

export const editMerchants = (value: FormData) => {
  return axios.put("merchant/update", value).then((res) => res.data);
};

export const updateMerchantStatus = (data: MerchantStatusUpdate) => {
  return axios.patch("merchant/update/status", data);
};

export const deleteMerchant = (id: string) => {
  return axios.delete(`/merchant/delete/${id}`).then((res) => res.data);
};

A few things to notice:

The import path is ./api — relative, short, scoped to the feature.
Shared types like MerchantStatusUpdate come from the global @/types index. Types stay global; functions don't.
Every export is a plain async function, not a class method. No instantiation, no inheritance, no this.
The CRUD surface is complete: GET (list and single), POST, PUT, PATCH, DELETE.

The logistics module shows how to absorb messy query parameters inside the function instead of leaking them into the signature:

// src/app/(AdminDashboard)/admin-logistics/api/index.ts

export const getLogisticsData = (
  search: string,
  selectedDate: { from?: Date; to?: Date },
  sort: string,
  page: string
) => {
  let startDate = "";
  let endDate = "";

  if (selectedDate?.from && selectedDate?.to) {
    startDate = selectedDate.from.toISOString().split("T")[0];
    endDate = selectedDate.to.toISOString().split("T")[0];
  }

  return axios
    .get("admin/shipping/list", {
      params: { search: search?.toLowerCase() || "", startDate, endDate, sort, page, limit: 10 },
    })
    .then((res) => res.data);
};

Date formatting and encoding happen inside the API function. The component passes a Date; the module hands the API a "YYYY-MM-DD" string. That's the boundary — the component doesn't know what format the API wants, and the API module doesn't know what the component's state looks like.

When a module reuses query-building logic across several endpoints, it reaches for a shared utility — never a shared API function:

// src/app/(AdminDashboard)/admin-settlement/api/index.ts

import { buildQueryParams } from "@/lib/utils";

export const getAdminSettlement = (
  page: number,
  selectedDate?: { from?: Date; to?: Date }
) => {
  const queryParams = buildQueryParams(selectedDate);
  return axios
    .get(`report/settlements?page=${page}&limit=10&${queryParams}`)
    .then((res) => res.data);
};

export const getAdminMomoSettlement = (
  page: number,
  selectedDate?: { from?: Date; to?: Date }
) => {
  const queryParams = buildQueryParams(selectedDate);
  return axios
    .get(`report/momo-settlements?page=${page}&limit=10&${queryParams}`)
    .then((res) => res.data);
};

buildQueryParams lives in @/lib/utils because it has zero API-specific knowledge — it's a string builder. The colocated module imports it. The rule holds: utilities can be shared; API functions cannot.

Wiring to React Query

The colocated functions plug straight into React Query's queryFn:

// src/app/(AdminDashboard)/admin-merchants/page.tsx

"use client";
import { useQuery } from "@tanstack/react-query";
import { getMerchants } from "./api";  // ← relative import, same directory

function AdminMerchants() {
  const [page, setPage] = useState<number>(1);
  const [search, setSearch] = useState("");
  const [activeTab, setActiveTab] = useState("active");

  const { data, isLoading } = useQuery<MerchantApiResponse>({
    queryKey: ["Merchants", page, search, activeTab],
    queryFn: () => getMerchants(page, search, activeTab),
  });

  // ...
}

The import is "./api", not "@/services/merchantService". The page and its API module are siblings. Move, rename, or delete the feature and everything travels together — there's no orphaned import in a distant services/ folder pointing at a module that no longer exists.

The merchant dashboard home fetches four statistics endpoints in parallel with useQueries, then wraps them into a single metrics array:

// src/hooks/useStatisticsQueries.ts

import {
  getProductStatistics,
  getOrderStatistics,
  getSalesStatistics,
  getProfitStatistics,
} from "@/app/(MerchantDashboard)/merchant-home/api";

export const useStatisticsQueries = (
  selectedOption: string,
  selectedDate: DateRange | undefined
) => {
  const queries = useQueries({
    queries: [
      {
        queryKey: ["getProductStatistics", selectedOption, selectedDate],
        queryFn: () => getProductStatistics(selectedOption || "today", selectedDate),
        select: (data: any) => transformApiResponse("productStatistics", data.dialogData),
      },
      {
        queryKey: ["getOrderStatistics", selectedOption, selectedDate],
        queryFn: () => getOrderStatistics(selectedOption || "today", selectedDate),
        select: (data: any) => transformApiResponse("totalOrder", data.dialogData),
      },
      // ...two more
    ],
  });

  return {
    metrics: Metrics.map((metric, i) => ({
      ...metric,
      dialogData: queries[i]?.data || metric.dialogData,
      isLoading: queries[i]?.isLoading,
    })),
    isLoading: queries.some((q) => q.isLoading),
  };
};

This is the one sanctioned exception to "import from ./api." When a cross-cutting hook aggregates data from several feature modules, it imports them by absolute path. But notice what it doesn't do: it doesn't invent a shared statistics service. It still pulls from each colocated module, which remains the single source of truth for its own requests. The boundary holds — the hook just reaches across it deliberately.

Query key design

React Query caches by the queryKey array, so keys are named after the domain entity and include every variable that changes the result:

queryKey: ["Merchants", page, search, activeTab, startDate, endDate]
queryKey: ["getProductStatistics", selectedOption, selectedDate]
queryKey: ["AdminSettlement", page, selectedDate]

That key drives three things:

Cache hits — the same key returns cached data with no network request.
Automatic refetch — change any array element and a fresh request fires.
Manual invalidation — queryClient.invalidateQueries({ queryKey: ["Merchants"] }) busts the entire merchant list cache.

The classic bug: you bury a variable inside queryFn but leave it out of queryKey. React Query has no idea the result changed, so paging or filtering silently serves stale data. The fix is mechanical — if it changes the response, it goes in the key.

What the pattern prevents

Accidental coupling. In a shared service file, it's tempting to write one function that hits three endpoints to "pre-assemble" what the UI needs — and now two features that should be independent are welded together. Colocation forces the question: does this extra call belong in merchant-inventory/api, or should it be a separate query? Usually, separate.

Namespace collisions. Both dashboards deal with inventory, locations, settlements, and orders. Centralized, you end up with getInventory, getMerchantInventory, getAdminInventory — or a flag like getInventory(role: 'admin' | 'merchant'). Colocated, getInventory in admin-inventory/api and getInventory in merchant-inventory/api are simply different modules. Same name, no collision.

Dead code. A function in a global services/ folder is hard to delete safely — you have to grep the whole codebase to be sure nothing else depends on it. A function in merchant-return/api/index.ts can only be reached by the merchant return feature. Delete the feature, delete the API file with it. "Find usages" stays honest.

The boundaries that have to stay global

Layer	Lives in	Why
HTTP client + interceptors	`src/components/Auth/Instance.ts`	All requests share auth, error handling, and base URL
Token management	`src/components/Auth/TokenService.ts`	Session state belongs to no single feature
Shared types	`src/types/index.ts`	Type definitions aren't API behavior
Pure utilities	`src/lib/utils.ts`	Date formatters and query builders have no feature ownership

Everything else — the actual HTTP calls — lives inside the feature directory.

Trade-offs, going in eyes open

Deliberate duplication. Some endpoints show up in more than one module. location/countries appears in both admin-merchants/api and admin-locations/api — on purpose. Both features need that data and probably shape it differently. A shared getCountries() couples them; two functions that happen to call the same endpoint keep them independent. If the URL changes, yes, you edit two files — but that's a known cost with a knowable scope (grep the endpoint, fix each hit). You never have to untangle shared state.

Discovery. Finding a specific call means navigating to its feature folder instead of opening one services file. If you already know which feature you're in, colocation is strictly faster. If the task is "find everywhere that calls settlements," you grep -r "settlements" — same operation either way.

Cross-feature data. When a hook legitimately spans features (like useStatisticsQueries), it imports from several colocated modules. That's fine. The alternative — a shared statistics service — would couple four independently owned features to satisfy a filing preference. Import from the modules; keep the module as the boundary.

Summary

Colocated APIs aren't a new idea — they're the same principle that makes route groups powerful: code that changes together should live together. In this retail POS project, the pattern holds across 30-plus modules, two dashboard contexts, and a three-role auth model. Each feature's API file is:

Discoverable — it's in the same folder as the page that uses it.
Deletable — removing the feature removes its calls automatically.
Independently testable — no shared state between modules.
Readable — a feature's entire API surface fits in one file.

The shared Axios instance handles the cross-cutting work — auth headers, session redirects, error toasts — once, for everything. The colocated modules handle only what their feature needs.

Adding a feature is always the same five steps: create a folder, add page.tsx, add api/index.ts, import the shared instance, export functions. No registration, no central manifest, no risk of breaking something unrelated.

That predictability is what makes it scale.

Have you run into the centralized-services/-folder sprawl on a large App Router project? I'd be curious how you've drawn the line between shared and colocated — drop a comment.

DEV Community: Philip Daniel Oghenetega