Dashboard Development Guide

This skill encodes the exact patterns and conventions used in this Next.js 16 + shadcn/ui admin dashboard template. Following these patterns ensures consistency across the codebase.

Quick Reference: What Goes Where

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 full guide. Forms use TanStack Form + Zod via useAppForm from @/lib/form (TanStack createFormHook). The shadcn TanStack Form doc anatomy lives once per widget in src/components/forms/fields/; pages render fields as one-liners:

import { useAppForm } from '@/lib/form';
import { FieldGroup } from '@/components/ui/field';

const form = useAppForm({
  defaultValues: { email: '', role: '' },
  validators: { onSubmit: schema }, // Zod schema — errors paint per field on submit
  onSubmit: async ({ value }) => {
    await createMutation.mutateAsync(value); // React Query mutation
  }
});

<form
  onSubmit={(e) => {
    e.preventDefault();
    form.handleSubmit();
  }}
>
  <FieldGroup>
    <form.AppField
      name='email' // typed against defaultValues — typos are compile errors
      children={(field) => <field.TextField label='Email' required type='email' />}
    />
    <form.AppField
      name='role'
      children={(field) => <field.SelectField label='Role' options={ROLE_OPTIONS} />}
    />
    <form.AppForm>
      <form.SubmitButton>Save</form.SubmitButton>
    </form.AppForm>
  </FieldGroup>
</form>

Available components (all take label, description?, required?): TextField (any input type; number converts at the edge, async-validator spinner built in), TextareaField (showCount), SelectField, CheckboxField, SwitchField, RadioGroupField, SliderField, ComboboxField, DatePickerField, DateRangeField, OtpField, ColorField, FileUploadField, CheckboxGroupField, TagsField, ToggleGroupField.

Rules:

• Array-valued components (CheckboxGroupField, TagsField, ToggleGroupField) need mode='array' on the form.AppField.
• Field-level validators/listeners (async checks, onChangeListenTo linked fields) go on the form.AppField element; function validators return { message: '…' } objects.
• One-off custom fields (object-row arrays, bespoke UI) drop down to raw form.Field render props composing Field/FieldLabel/FieldError from @/components/ui/field — data-invalid on Field, aria-invalid on the control, {isInvalid && <FieldError errors={field.state.meta.errors} />}.
• Large forms split into typed sections with withForm from @/lib/form (section receives form as a prop; field names stay compile-checked).
• Sheet/Dialog forms: submit button in the footer via the HTML form attribute (<Button type='submit' form='my-form-id'>).
• Multi-step: useFormStepper(stepSchemas, { fullSchema }) from @/hooks/use-stepper; route every submit through handleNextStepOrSubmit(form).
• Match the widget to the path's value type — the compiler checks the name path but NOT the widget/value pairing (a SwitchField on a string path compiles and misbehaves).
• Never call useState inside a render prop — extract stateful controls into components.

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