DEV Community: Philip Daniel Oghenetega

Why We Chose Radix UI + Tailwind Over a Full Component Library for a POS App

Philip Daniel Oghenetega — Thu, 13 Aug 2026 07:49:38 +0000

Enterprise admin tools have a reputation problem: they tend to look like whatever component library they were built with. You can spot a stock MUI dashboard or a default Ant Design table from across the room. For most internal tools, that's a fair trade — you get sorting, theming, and forms for free, and nobody minds that it looks like every other admin panel.

We didn't have that luxury. Our product is a retail POS platform used by merchants and users who interact with our brand daily, across a dozen-plus surfaces — dashboards, tables, forms, modals, mobile card views. It needed to look like us, not like a component library's default theme with our logo pasted on top. So we built on Radix UI primitives and Tailwind CSS instead of adopting a full component library, and after growing that decision across dozens of screens, it's held up.

Here's the actual trade-off, based on how it played out.

What "headless + utility-first" means in practice

Radix UI ships unstyled, accessible primitives — dialog, dropdown menu, select, popover, tabs, toast, tooltip, and more. It handles the hard, easy-to-get-wrong parts (focus trapping in a modal, keyboard navigation in a dropdown, ARIA attributes, portal rendering) and hands you zero opinions about how anything should look.

That means every primitive needs a wrapper before it's usable in product code. We have roughly 22 Radix-backed components living in a src/components/ui/ folder — button, dialog, select, dropdown-menu, popover, tooltip, switch, tabs, and so on — each one a thin, styled layer over the matching Radix primitive. On top of those, product code builds feature-specific components — a Modal wrapper around Dialog that adds our standard header/footer layout, for instance.

Three layers: unstyled behavior (Radix) → styled primitive (our ui/ folder) → product component (feature code). Nobody outside that middle layer touches Radix directly.

// src/components/ui/button.tsx — Radix Slot + cva variants
const buttonVariants = cva(
  "inline-flex items-center justify-center rounded-md text-sm font-medium ...",
  {
    variants: {
      variant: { default: "...", destructive: "...", outline: "...", ghost: "..." },
      size: { default: "h-10 px-4 py-2", sm: "h-9 px-3", lg: "h-11 px-8", icon: "h-10 w-10" },
    },
    defaultVariants: { variant: "default", size: "default" },
  },
);

This is the shadcn/ui pattern — class-variance-authority (cva) for variant management, a cn() helper combining clsx and tailwind-merge for conditional class composition. We never ran the shadcn CLI scaffold or committed a components.json; the pattern was adopted by convention and grew organically, one primitive at a time, as screens needed them. You can see that incrementalism in the commit history itself — commits like "switch added" and "tabs added" rather than one big design-system PR.

Branding lives in the theme layer, not fought against a library's defaults

The entire point of this approach is that visual identity is a config file, not a battle. tailwind.config.ts extends Tailwind's default theme with our brand color scale, semantic design tokens (background, foreground, card, muted, accent, and sidebar-specific variants) expressed as CSS variables so dark mode is a variable swap rather than a duplicated theme object, our brand typeface, and custom keyframe animations for open/close transitions on Radix's dialogs and dropdowns.

// tailwind.config.ts (shape, not actual values)
extend: {
  colors: {
    primary: {
      DEFAULT: "hsl(var(--primary))",
      hover: "hsl(var(--primary-hover))",
    },
    background: "hsl(var(--background))",
    sidebar: { DEFAULT: "hsl(var(--sidebar-bg))" },
  },
  keyframes: {
    "slide-down-fade": { /* Radix data-state driven */ },
  },
},

Because Radix components expose state as data attributes (data-state="open", data-state="closed"), the animation layer can hook directly into them via Tailwind's data-[state=...] variants — no JS-driven animation library needed, no fighting a component library's own transition system.

Accessibility came largely for free — which almost never gets mentioned in "why headless" pitches

The usual pitch for headless UI is composability and bundle size. In practice, the accessibility story mattered just as much and required less deliberate effort than expected. Radix bakes in focus management, aria-selected/aria-expanded state, roving tabindex for menus, and portal-based layering for dialogs and popovers.

Our wrapper components only had to add a handful of sr-only labels for icon-only buttons and explicit role/aria-label attributes on custom-built pieces like pagination controls. Nobody on the team sat down and implemented a focus trap; it came with the primitive.

The honest cost: composability requires discipline you don't get automatically

This is the part libraries like MUI or Ant Design solve by fiat — there's one <Table>, one <Modal>, one toast system, and everyone uses it because there's no alternative bundled in. Headless + utility-first doesn't enforce that for you.

Case in point: we have a fully custom Radix-based toast system (Toast/Toaster/useToast) and react-toastify as a direct dependency, both still in use. That's not a design decision — it's the residue of incremental adoption, where a screen was built against whichever pattern was fastest to reach for at the time, and nobody has gone back to unify them. A component library would never have let that happen, because it would only have shipped one toast API in the first place.

That's the real trade-off, stated plainly: a component library buys you consistency as a default. Headless primitives buy you flexibility as a default, and consistency becomes something the team has to actively maintain — through conventions, code review, and periodically going back to consolidate drift like the toast situation above. We think that trade was correct for a product where the UI is the brand. It would be a worse trade for an internal tool where nobody cares what the dropdown looks like, as long as it works.

Where this leaves us

For a branded, complex, enterprise product, the calculus came down to this: a full component library optimizes for speed-to-first-screen and gives you consistency you didn't have to design. Radix + Tailwind optimizes for the fiftieth screen looking as intentional as the first, at the cost of building and maintaining that consistency yourselves.

We picked the second because the product's UI needed to be a differentiator, not a commodity — and twenty-some wrapped primitives later, we'd make the same call again.

We'd just go back and merge those two toast systems first.

Have you gone headless on a production app? Did the consistency drift bite you too, or did your team find a way to enforce conventions early? Curious what's worked for others.

Building Data-Heavy Tables with TanStack Table v8 in Next.js (Using 10% of the Library on Purpose)

Philip Daniel Oghenetega — Thu, 13 Aug 2026 07:08:48 +0000

I am working on a retail POS platform with many tables. Canvassers, merchants, inventory, transactions, settlements, terminals, orders, returns, invoices, campaigns, wallets — by the time you count every list view across the admin and merchant dashboards, you're well past fifty distinct table screens. Each one needs sorting, filtering, and pagination against datasets that can run into the tens of thousands of rows.

We use TanStack Table v8 for all of them. But if you went looking through our codebase for getSortedRowModel, SortingState, or getFilteredRowModel, you wouldn't find them. We use maybe 10% of what the library offers — and that turned out to be the right call.

This post is about what we built, and more usefully, why we deliberately didn't reach for the rest of the API.

One component, not fifty

The first decision that mattered wasn't about TanStack Table at all — it was about not repeating ourselves. Every table in the app renders through a single generic component:

type DataTableProps<TData, TValue> = {
  columns: ColumnDef<TData, TValue>[];
  data: TData[];
  isLoading?: boolean;
  currentPage: number;
  totalPages: number;
  pageSize: number;
  onPageChange: (page: number) => void;
  onPageSizeChange: (size: number) => void;
  notFoundText?: string;
};

function DataTable<TData, TValue>({ columns, data, ...pagination }: DataTableProps<TData, TValue>) {
  const table = useReactTable({
    data,
    columns,
    getCoreRowModel: getCoreRowModel(),
  });

  // render skeleton | empty state | table (desktop) | cards (mobile) + pagination
}

That's the entire useReactTable call — getCoreRowModel() and nothing else. Every feature page supplies columns and data, and gets header rendering, cell rendering, a loading skeleton, an empty state, and a fully responsive layout for free. On mobile, the same ColumnDef array that builds table headers/cells also builds a card layout — one card per row — so we're not maintaining a second UI for small screens.

The payoff: adding a table for a new entity is a matter of writing a column definition file and a data-fetching hook. Nobody re-implements pagination controls or loading spinners.

Column definitions: `accessorKey` for data, `id` + `cell` for everything else

Most columns are a direct passthrough:

const columns: ColumnDef<Merchant>[] = [
  {
    accessorKey: "businessName",
    header: "Business Name",
  },
  {
    accessorKey: "email",
    header: "Email",
  },
];

But a lot of our real columns aren't plain fields — they're a status badge, a formatted currency value, a name built from two fields, or a dropdown of row actions. For those we skip accessorKey/accessorFn entirely and use an id + custom cell, reading straight off row.original:

{
  id: "status",
  header: "Status",
  cell: ({ row }) => <StatusBadge status={row.original.status} />,
},
{
  id: "actions",
  header: "",
  cell: ({ row }) => <RowActionsMenu record={row.original} />,
},

For actions that need router access (navigate to a detail page, open a modal, trigger a mutation), the column array is built inside a small useXColumns() hook rather than defined as a static export, so it can close over router, queryClient, and any dialog state it needs.

The interesting part: we don't sort or filter with the table

This is the part that surprises people who've used TanStack Table before. There's no SortingState, no onSortingChange, no clickable column headers, no globalFilter. Every table's sort order, search term, status filter, and date range live in plain page-level state and get sent to the API:

const [page, setPage] = useState(1);
const [limit, setLimit] = useState(10);
const [search, setSearch] = useState("");
const [status, setStatus] = useState<string>();

const { data, isLoading } = useQuery({
  queryKey: ["merchants", page, limit, search, status],
  queryFn: () => fetchMerchants({ page, limit, search, status }),
  placeholderData: keepPreviousData,
});

The "sort" control is just a <Select> whose value gets appended to the same query params. The API does the actual ordering, filtering, and slicing, and returns { data, count, totalPages }. DataTable just renders whatever page of rows it's handed.

Why not let TanStack Table's row models do this client-side? Because our datasets don't fit in a browser tab. A transactions table can span months of records; fetching everything and sorting/filtering in memory doesn't scale, and it also doesn't match how the rest of the system already thinks about data. Our APIs are already paginated and filterable, so pushing sort/filter/paginate to the server keeps one source of truth for "what does page 3 of this query look like" — instead of two (server pagination plus client row-model logic layered on top of it).

TanStack Query's keepPreviousData (now placeholderData: keepPreviousData in v5) is what makes this feel smooth — when the search term or page changes, the old rows stay on screen instead of flashing an empty/loading state while the new request resolves.

Pagination: server-driven, one shared control

Pagination follows the same philosophy. DataTable never touches getPaginationRowModel — it renders exactly the array it's given. Page number, page size, and total count all come from the API response and flow into a shared <CustomPagination /> component: page buttons with ellipsis for large ranges, a page-size selector, a "jump to page" input, and a results count. It's rendered twice inside DataTable — once for the desktop table view, once for the mobile card view — so both layouts stay in sync automatically.

Loading and empty states, baked in

Rather than every page hand-rolling a spinner, DataTable accepts isLoading and renders animated skeleton rows matching the current column count, then falls back to a configurable empty state (icon + message) when the row count is zero.

A couple of older pages predate this and swap in a standalone LoadingTable component at the call site instead — a good reminder that once you have a shared component, it's worth going back and migrating the stragglers rather than letting two patterns coexist indefinitely.

What we'd change

Nothing here is gospel. The most obvious gap: search inputs fire a new request on every keystroke, relying on keepPreviousData to hide the flicker. It works, but it's more network traffic than necessary — a useDebouncedValue around the search term before it hits the query key would cut request volume meaningfully with no UX cost. It's on our list.

We also don't do row selection, expandable rows, or virtualization anywhere yet. For our current page sizes (10–50 rows, server-paginated) that's fine; if a future table needs to show thousands of rows at once without pagination, that's when @tanstack/react-virtual earns its place — not before.

The actual lesson

TanStack Table is often introduced as a batteries-included package: sorting, filtering, pagination, selection, grouping, virtualization, all wired through row models. The useful realization for us wasn't learning that API surface — it was recognizing that our tables didn't need most of it. TanStack Table earns its keep here purely as a rendering layer: it turns a ColumnDef array into consistent headers and cells, and gets out of the way of everything else. Sorting, filtering, and pagination are business logic that already lived on our server, and duplicating that logic client-side would have been the actual mistake.

If you're reaching for TanStack Table on a data-heavy admin panel, the first question worth asking isn't "which row models do I need" — it's "which of these concerns does my backend already own."

For us, the answer was: most of them.

How do you handle tables in your admin panels — client-side row models or server-driven? I'd love to hear where you landed and why.

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.