Dashboard Development Guide

Adding a New Feature (End-to-End)

When a user asks to add a new feature (e.g., "add a users page", "create an orders section"), follow all these steps in order:

1. Create mock API in src/constants/mock-api-<name>.ts
2. Create query options in src/features/<name>/api/queries.ts
3. Create the feature module in src/features/<name>/components/
4. Create the page route in src/app/dashboard/<name>/page.tsx
5. Add search params in src/lib/searchparams.ts (if table/filtering needed)
6. Add navigation in src/config/nav-config.ts
7. Register icon in src/components/icons.tsx (if new icon needed)

1. Data Fetching with React Query

The project uses TanStack React Query for data fetching with server-side prefetching and client-side cache management. This is the default pattern for all new pages.

Query Options (api/queries.ts)

Define reusable query options shared between server prefetch and client hooks:

import { queryOptions } from '@tanstack/react-query';
import { fakeEntities, type Entity } from '@/constants/mock-api-entities';

export type { Entity };

export const entitiesQueryOptions = (filters: { page?: number; limit?: number; search?: string }) =>
  queryOptions({
    queryKey: ['entities', filters],
    queryFn: () => fakeEntities.getEntities(filters)
  });

Server Prefetch + Client Hydration (Listing Component)

import { HydrationBoundary, dehydrate } from '@tanstack/react-query';
import { getQueryClient } from '@/lib/query-client';
import { searchParamsCache } from '@/lib/searchparams';
import { entitiesQueryOptions } from '../api/queries';
import { EntityTable, EntityTableSkeleton } from './entity-table';
import { Suspense } from 'react';

export default function EntityListingPage() {
  const page = searchParamsCache.get('page');
  const search = searchParamsCache.get('name');
  const pageLimit = searchParamsCache.get('perPage');

  const filters = { page, limit: pageLimit, ...(search && { search }) };

  const queryClient = getQueryClient();
  void queryClient.prefetchQuery(entitiesQueryOptions(filters));

  return (
    <HydrationBoundary state={dehydrate(queryClient)}>
      <Suspense fallback={<EntityTableSkeleton />}>
        <EntityTable />
      </Suspense>
    </HydrationBoundary>
  );
}

Client Table Component (shallow: true + useQuery)

'use client';

import { useQuery } from '@tanstack/react-query';
import { parseAsInteger, useQueryState } from 'nuqs';
import { useDataTable } from '@/hooks/use-data-table';
import { entitiesQueryOptions } from '../../api/queries';
import { columns } from './columns';

export function EntityTable() {
  const [page] = useQueryState('page', parseAsInteger.withDefault(1));
  const [pageSize] = useQueryState('perPage', parseAsInteger.withDefault(10));
  const [search] = useQueryState('name');

  const filters = { page, limit: pageSize, ...(search && { search }) };

  const { data, isLoading } = useQuery(entitiesQueryOptions(filters));

  const { table } = useDataTable({
    data: data?.items ?? [],
    columns,
    pageCount: Math.ceil((data?.total_items ?? 0) / pageSize),
    shallow: true, // URL changes stay client-side — React Query handles fetching
    debounceMs: 500,
    initialState: { columnPinning: { right: ['actions'] } }
  });

  if (isLoading) return <DataTableSkeleton columnCount={5} rowCount={10} filterCount={2} />;

  return (
    <DataTable table={table}>
      <DataTableToolbar table={table} />
    </DataTable>
  );
}

Key points:

• shallow: true — URL changes stay client-side, React Query fetches on the client
• shallow: false — triggers full RSC server navigation (legacy pattern, avoid for new pages)
• First load uses hydrated server-prefetched data (no loading spinner)
• Subsequent pagination/filter changes fetch on the client
• Cached pages/filters load instantly (React Query cache)

Mutations (Forms)

const queryClient = useQueryClient();

const createMutation = useMutation({
  mutationFn: (data: Payload) => fakeEntities.createEntity(data),
  onSuccess: () => {
    queryClient.invalidateQueries({ queryKey: ['entities'] });
    toast.success('Created successfully');
    router.push('/dashboard/entities');
  },
  onError: () => toast.error('Failed to create')
});

// In useAppForm onSubmit:
onSubmit: async ({ value }) => {
  await createMutation.mutateAsync(payload);
};

2. Page Structure

Pages are server components by default. They use PageContainer and accept search params as a Promise (Next.js 16 pattern).

import PageContainer from '@/components/layout/page-container';
import EntityListingPage from '@/features/entities/components/entity-listing';
import { searchParamsCache } from '@/lib/searchparams';
import type { SearchParams } from 'nuqs/server';

export const metadata = { title: 'Dashboard: Entities' };

type PageProps = { searchParams: Promise<SearchParams> };

export default async function Page(props: PageProps) {
  const searchParams = await props.searchParams;
  searchParamsCache.parse(searchParams);

  return (
    <PageContainer
      scrollable={false}
      pageTitle='Entities'
      pageDescription='Manage entities (React Query + nuqs table pattern.)'
    >
      <EntityListingPage />
    </PageContainer>
  );
}

3. Data Tables

Tables use TanStack Table v8 with useDataTable hook and nuqs for URL state.

Column Definitions

export const columns: ColumnDef<YourType>[] = [
  {
    id: 'name',
    accessorKey: 'name',
    header: ({ column }) => <DataTableColumnHeader column={column} title='Name' />,
    meta: { label: 'Name', placeholder: 'Search...', variant: 'text', icon: Icons.text },
    enableColumnFilter: true
  },
  {
    id: 'category',
    accessorKey: 'category',
    enableColumnFilter: true,
    meta: { label: 'Category', variant: 'multiSelect', options: CATEGORY_OPTIONS }
  },
  {
    id: 'actions',
    cell: ({ row }) => <CellAction data={row.original} />
  }
];

Column Pinning

initialState: {
  columnPinning: {
    right: ['actions'];
  }
}

Filter variants: text, number, range, date, dateRange, select, multiSelect, boolean

4. Forms

See docs/forms.md for the complete form system. Forms use TanStack Form + Zod with useAppForm + useFormFields<T>() and useMutation for submission.

5. Navigation, Search Params, Icons, Themes

• Nav: src/config/nav-config.ts — groups with RBAC access property
• Search params: src/lib/searchparams.ts — add new params with parseAsString/parseAsInteger
• Icons: src/components/icons.tsx — single source of truth, never import @tabler/icons-react directly
• Themes: src/styles/themes/<name>.css with OKLCH colors, register in theme.config.ts

Code Conventions

• cn() for class merging — never concatenate className strings
• Server components by default — only add 'use client' when needed
• React Query for data fetching — useQuery + shallow: true for tables, useMutation for forms
• nuqs for URL state — searchParamsCache on server, useQueryState on client
• Formatting: single quotes, JSX single quotes, no trailing comma, 2-space tabs