doo-boilerplate 0.2.14 → 0.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "doo-boilerplate",
-  "version": "0.2.14",
+  "version": "0.3.0",
   "description": "CLI to scaffold Pila portal frontend projects",
   "type": "module",
   "bin": {
@@ -8,7 +8,10 @@
     "create-pila-app": "./dist/index.js"
   },
   "main": "./dist/index.js",
-  "files": ["dist", "templates"],
+  "files": [
+    "dist",
+    "templates"
+  ],
   "scripts": {
     "build": "tsup",
     "dev": "tsup --watch",

package/templates/template-vite/.claude/commands/debug.md

@@ -0,0 +1,24 @@
+# Debug an Issue
+
+Use this prompt to systematically debug a problem in this project.
+
+## Prompt
+
+```
+Debug this issue: [DESCRIBE THE BUG]
+
+Steps:
+1. Reproduce — identify exact steps to trigger the issue
+2. Locate — search relevant files:
+   - Error in UI? → src/features/ or src/components/
+   - API error? → src/lib/api-client.ts, src/features/*/data/
+   - Route issue? → src/routes/, routeTree.gen.ts
+   - State issue? → src/stores/
+3. Read error — check browser console / Sentry for stack trace
+4. Root cause — trace the call chain, identify the failing assertion
+5. Fix — minimal change, do not refactor unrelated code
+6. Verify:
+   - pnpm lint && pnpm type-check
+   - Manually test the fixed flow
+7. Commit: fix([scope]): [what was broken and how fixed]
+```

package/templates/template-vite/.claude/commands/feature.md

@@ -0,0 +1,31 @@
+# Implement a Feature
+
+Use this prompt to implement a new feature module in this project.
+
+## Prompt
+
+```
+Implement the feature: [FEATURE_NAME]
+
+Context:
+- Read CLAUDE.md for project conventions
+- Feature dir: src/features/[name]/
+- Route: src/routes/_authenticated/[name].tsx
+- Nav: src/components/layout/sidebar.tsx
+
+Steps:
+1. Create src/features/[name]/ with:
+   - types/[name].types.ts — TypeScript interfaces
+   - schemas/[name].schema.ts — zod validation schemas
+   - data/use-[name].ts — TanStack Query hooks
+   - components/[name]-list.tsx — list view using DataTable
+   - components/[name]-form.tsx — create/edit form
+2. Add route file at src/routes/_authenticated/[name].tsx
+3. Register nav item in src/components/layout/sidebar.tsx
+4. Wire API calls through src/lib/api-client.ts
+
+After implementation:
+- Run: pnpm lint && pnpm type-check
+- Fix any lint/type errors before finishing
+- Follow conventional commits: feat([name]): add [description]
+```

package/templates/template-vite/.claude/commands/plan.md

@@ -0,0 +1,30 @@
+# Plan an Implementation
+
+Use this prompt to plan a feature or change before writing code.
+
+## Prompt
+
+```
+Plan the implementation for: [FEATURE OR CHANGE]
+
+Steps:
+1. Read CLAUDE.md for project context and conventions
+2. Analyze requirements — list what needs to be built
+3. Identify affected files:
+   - New feature? → src/features/[name]/
+   - New route? → src/routes/_authenticated/
+   - Shared component? → src/components/
+   - API change? → src/lib/api-client.ts
+4. Define phases (if complex):
+   - Phase 1: types + schemas
+   - Phase 2: API hooks (TanStack Query)
+   - Phase 3: UI components
+   - Phase 4: route + nav integration
+5. Success criteria:
+   - pnpm lint && pnpm type-check pass
+   - Feature works end-to-end
+   - No regressions in existing routes
+6. Risks: list potential blockers or edge cases
+
+Output: numbered implementation steps ready to execute
+```

package/templates/template-vite/.claude/commands/review.md

@@ -0,0 +1,24 @@
+# Code Review
+
+Use this prompt to review code changes in this project.
+
+## Prompt
+
+```
+Review the following code changes: [FILE(S) OR DIFF]
+
+Checklist:
+- [ ] TypeScript types are explicit (no `any` unless justified)
+- [ ] Error handling: API calls wrapped in try/catch or TanStack Query error state
+- [ ] Naming: kebab-case files, camelCase vars, PascalCase components
+- [ ] No unused imports/exports (run `pnpm knip` to verify)
+- [ ] Zod schemas match API response shape
+- [ ] No hardcoded strings — use i18n keys or constants
+- [ ] No secrets or API keys in code
+- [ ] lint-staged passes: pnpm lint && pnpm format:check
+- [ ] Type check passes: pnpm type-check
+- [ ] Follows feature-based structure in src/features/
+
+Rate each: Pass / Warn / Fail
+Summary: overall assessment + top 3 issues to fix
+```

package/templates/template-vite/.husky/commit-msg

@@ -0,0 +1 @@
+pnpm commitlint --edit $1

package/templates/template-vite/.husky/pre-commit

@@ -0,0 +1 @@
+pnpm lint-staged

package/templates/template-vite/CLAUDE.md

@@ -1,47 +1,135 @@
-# CLAUDE.md
+# {{PROJECT_NAME}}
 
 This file provides guidance to Claude Code when working in this project.
 
 ## Tech Stack
-- React 19, TypeScript, Vite 8
-- TanStack Router (file-based routing) — add routes in `src/routes/`
-- TanStack Query — data fetching via `useQuery`/`useMutation`
-- TanStack Table — data tables via `src/components/data-table/`
-- Tailwind CSS 4 + shadcn/ui components in `src/components/ui/`
-- Zustand — global state in `src/stores/`
-- react-hook-form + zod — forms with validation
-- Sentry — error tracking (set `VITE_SENTRY_DSN` in `.env`)
+
+- Vite 8, React 19, TypeScript 5
+- Tailwind CSS 4 + shadcn/ui (Radix UI primitives)
+- TanStack Router (file-based routing), TanStack Query, TanStack Table
+- Zustand (global state), react-hook-form + zod (forms)
+- i18next (internationalization), Sentry (error tracking), Axios (HTTP)
 
 ## Project Structure
-- `src/routes/` — file-based routes (TanStack Router auto-generates `routeTree.gen.ts`)
-- `src/features/` — feature modules (each has components/, hooks/, types/, schemas/, data/)
-- `src/components/ui/` — shadcn/ui components
-- `src/components/data-table/` — reusable DataTable components
-- `src/components/layout/` — Sidebar, Header, PageLayout
-- `src/lib/` — utilities (api-client, query-client, sentry, utils)
-- `src/stores/` — Zustand stores
-
-## Development Commands
+
+```
+src/
+  routes/        # file-based routes — auto-generates routeTree.gen.ts
+  features/      # feature modules: components/, hooks/, services/, types/, schemas/
+  components/
+    ui/          # shadcn/ui components
+    data-table/  # reusable DataTable
+    layout/      # Sidebar, Header, PageLayout
+  lib/           # api-client, query-client, sentry, utils
+  stores/        # Zustand stores
+  config/        # app configuration
+  context/       # React contexts
+  hooks/         # shared hooks
+  types/         # shared types
+```
+
+## Dev Commands
+
 ```bash
-pnpm dev          # start dev server
-pnpm build        # build for production
-pnpm type-check   # TypeScript check
-pnpm lint         # ESLint
+pnpm dev           # start dev server
+pnpm build         # TypeScript check + Vite build
+pnpm lint          # ESLint check
+pnpm lint:fix      # ESLint auto-fix
+pnpm type-check    # tsc --noEmit
+pnpm format        # Prettier write
+pnpm format:check  # Prettier check
+pnpm knip          # detect unused exports/deps
+pnpm docker:build  # build Docker image + Trivy scan
+pnpm docker:scan   # Trivy security scan only
 ```
 
-## Adding a New Feature Module
-1. Create `src/features/{name}/` with: types/, schemas/, components/, data/
+## Code Conventions
+
+- **File naming:** kebab-case
+- **Feature structure:** group by domain in `src/features/{name}/`
+- **Commits:** conventional commits enforced by commitlint + Husky
+- **Pre-commit:** ESLint + Prettier run automatically via lint-staged
+- **Routes:** auto-discovered — create file in `src/routes/`, run `pnpm dev` to regenerate
+
+## Adding a Feature
+
+1. Create `src/features/{name}/` with: `types/`, `schemas/`, `services/`, `hooks/`, `components/`
 2. Add route at `src/routes/_authenticated/{name}.tsx`
 3. Add nav item in `src/components/layout/sidebar.tsx`
-4. Use `DataTable` from `src/components/data-table/data-table.tsx` for list views
+4. Use `DataTable` from `src/components/data-table/` for list views
+5. Use TanStack Query hooks + `src/lib/api-client.ts` for API calls
 
-## Adding New Routes
-Routes are auto-discovered. Create a file in `src/routes/` and run `pnpm dev` to regenerate `routeTree.gen.ts`.
+## Environment Variables
 
-## API Integration
-Replace mock data in `src/features/*/data/` with real API calls using `src/lib/api-client.ts` (axios).
-Use TanStack Query hooks for data fetching.
+Copy `.env.example` to `.env`. Key vars:
+- `VITE_SENTRY_DSN` — Sentry DSN (optional)
 
-## Environment Variables
-Copy `.env.example` to `.env` and fill in values.
-`VITE_SENTRY_DSN` — Sentry DSN for error tracking (optional)
+## Library-Specific Rules
+
+### Tailwind CSS v4
+- No `tailwind.config.js` — config lives in CSS via `@theme` block
+- Use `@utility` to define custom utilities, NOT `@apply` for component styles
+- CSS variables for design tokens: `var(--color-primary)`, `var(--spacing-4)`
+- Import: `import '@/styles/globals.css'` (single entry, no per-component imports)
+- Dark mode: use `dark:` variant, toggled via `next-themes` `ThemeProvider`
+
+### TanStack Router
+- File-based routing only — create files in `src/routes/`, never manually edit `routeTree.gen.ts`
+- Every route file must export via `createFileRoute('...')` — path must match filename exactly
+- Authenticated routes go under `src/routes/_authenticated/` (wrapped by auth layout)
+- Navigation: `useNavigate()` hook or `<Link to="...">`, never `window.location`
+- Params: `const { id } = Route.useParams()`, search: `Route.useSearch()`
+- Lazy load heavy routes: `export const Route = createLazyFileRoute(...)`
+
+### TanStack Query
+- Prefer `useSuspenseQuery` over `useQuery` — wrap route component in `<Suspense>`
+- Query keys: array format `['resource', id]` or `['resource', 'list', filters]`
+- Mutations: `useMutation` + `onSuccess: () => queryClient.invalidateQueries(...)`
+- Global config in `src/lib/query-client.ts` — do not create new QueryClient instances
+- All API calls go through `src/lib/api-client.ts` (axios instance with auth headers)
+
+### shadcn/ui
+- Components live in `src/components/ui/` — do not edit them directly
+- Add new components: `pnpm dlx shadcn@latest add <component>`
+- Compose with Radix primitives when shadcn doesn't have what you need
+- Use `cn()` from `src/lib/utils.ts` for conditional class merging (not `clsx` directly)
+
+### react-hook-form + zod
+- Always define schema with `z.object({...})` in `src/features/{name}/schemas/`
+- Use `useForm<z.infer<typeof schema>>({ resolver: zodResolver(schema) })`
+- Never use uncontrolled inputs — always register with `{...register('field')}`
+
+### Zustand
+- One store per feature domain in `src/stores/`
+- Never store server data in Zustand — server state belongs in TanStack Query
+- Use immer middleware for nested state updates
+
+### i18n
+- All user-facing strings must use `useTranslation()` — no hardcoded UI text
+- Key format: `"feature.action.noun"` (e.g. `"user.form.submit"`)
+- Translation files: `src/locales/{en,vi}/translation.json`
+
+## API Patterns
+
+- Auth: Bearer token in `Authorization` header — handled automatically by `src/lib/api-client.ts` interceptor
+- Success response shape: `{ data: T, message: string, success: boolean }`
+- Error response shape: `{ message: string, errors: Record<string, string[]> }`
+- Base URL: `import.meta.env.VITE_API_URL`
+- Never create axios instances directly — always import from `src/lib/api-client.ts`
+
+## Anti-Patterns — Never Do These
+
+- **No `useEffect` for data fetching** — use TanStack Query (`useSuspenseQuery` / `useQuery`)
+- **No `React.FC`** — use `function Component(): JSX.Element`
+- **No `any`** — use `unknown` + type guard or proper types
+- **No business logic in route files** — put in `src/features/`
+- **No direct edits to `src/components/ui/`** — add components via `pnpm dlx shadcn@latest add`
+- **No manual edits to `routeTree.gen.ts`** — auto-generated, regenerates on `pnpm dev`
+- **No new `QueryClient` instances** — use the one from `src/lib/query-client.ts`
+- **No hardcoded UI strings** — use i18n keys
+
+## Claude AI Workflow
+
+- Slash commands available: `/feature`, `/debug`, `/review`, `/plan` (see `.claude/commands/`)
+- Always run `pnpm lint && pnpm type-check` after code changes
+- Follow conventional commits: `feat:`, `fix:`, `chore:`, `refactor:`, `docs:`

package/templates/template-vite/_env.example

@@ -1,6 +1,5 @@
-# API Configuration
+# API
 VITE_API_URL=http://localhost:8000
-VITE_API_AUTH_URL=http://localhost:8001
 
 # App
 VITE_APP_URL=http://localhost:3000

package/templates/template-vite/_package.json

@@ -16,7 +16,8 @@
     "gen:api": "swagger-typescript-api -p ./docs/swagger/api.json -o ./src/features/auth/services/gen --no-client --modular",
     "gen:api:watch": "swagger-typescript-api -p ./docs/swagger/api.json -o ./src/features/auth/services/gen --no-client --modular --watch",
     "docker:build": "bash scripts/build-and-scan.sh",
-    "docker:scan": "bash scripts/trivy-scan.sh"
+    "docker:scan": "bash scripts/trivy-scan.sh",
+    "prepare": "is-ci || husky"
   },
   "dependencies": {
     "@sentry/react": "^9.0.0",
@@ -87,7 +88,10 @@
     "prettier": "^3.6.2",
     "prettier-plugin-tailwindcss": "^0.6.11",
     "@trivago/prettier-plugin-sort-imports": "^4.3.0",
+    "@commitlint/cli": "^19.8.1",
+    "@commitlint/config-conventional": "^19.8.1",
     "husky": "^9.1.7",
+    "is-ci": "^3.0.1",
     "lint-staged": "^15.2.11",
     "knip": "^5.64.2",
     "swagger-typescript-api": "^13.2.7",

package/templates/template-vite/commitlint.config.ts

@@ -0,0 +1,3 @@
+export default {
+  extends: ['@commitlint/config-conventional'],
+}

package/templates/template-vite/src/features/tasks/components/tasks-crud-table.tsx

@@ -11,11 +11,10 @@ import {
   type VisibilityState,
 } from '@tanstack/react-table'
 import { Plus } from 'lucide-react'
-import { toast } from 'sonner'
 import { Button } from '@/components/ui/button'
 import { DataTable } from '@/components/data-table/data-table'
 import { DataTableToolbar } from '@/components/data-table/data-table-toolbar'
-import { tasksMockData } from '../data/tasks-mock-data'
+import { useTasks, useCreateTask, useUpdateTask, useDeleteTask } from '../hooks/use-tasks'
 import { getTaskColumns } from './tasks-table-columns'
 import { TaskFormDialog } from './task-form-dialog'
 import type { Task } from '../types/task'
@@ -34,9 +33,13 @@ const PRIORITY_FILTER_OPTIONS = [
   { label: 'High', value: 'high' },
 ]
 
-/** Full CRUD data table for tasks using local state */
+/** CRUD data table for tasks — data fetched via TanStack Query, mutations invalidate cache */
 export function TasksCrudTable() {
-  const [tasks, setTasks] = useState<Task[]>(tasksMockData)
+  const { data: response, isLoading } = useTasks()
+  const createTask = useCreateTask()
+  const updateTask = useUpdateTask()
+  const deleteTask = useDeleteTask()
+
   const [sorting, setSorting] = useState<SortingState>([])
   const [columnFilters, setColumnFilters] = useState<ColumnFiltersState>([])
   const [columnVisibility, setColumnVisibility] = useState<VisibilityState>({})
@@ -45,36 +48,23 @@ export function TasksCrudTable() {
   const [dialogOpen, setDialogOpen] = useState(false)
   const [editingTask, setEditingTask] = useState<Task | undefined>()
 
-  const handleEdit = (task: Task) => {
-    setEditingTask(task)
-    setDialogOpen(true)
-  }
-
-  const handleDelete = (id: string) => {
-    setTasks((prev) => prev.filter((t) => t.id !== id))
-    toast.success('Task deleted')
-  }
+  const handleEdit = (task: Task) => { setEditingTask(task); setDialogOpen(true) }
+  const handleDelete = (id: string) => deleteTask.mutate(id)
 
   const handleSubmit = (values: TaskFormValues) => {
     if (editingTask) {
-      setTasks((prev) => prev.map((t) => t.id === editingTask.id ? { ...t, ...values } : t))
-      toast.success('Task updated')
+      updateTask.mutate({ id: editingTask.id, data: values })
     } else {
-      const newTask: Task = {
-        id: String(Date.now()),
-        ...values,
-        createdAt: new Date().toISOString().slice(0, 10),
-      }
-      setTasks((prev) => [newTask, ...prev])
-      toast.success('Task created')
+      createTask.mutate(values)
     }
     setEditingTask(undefined)
   }
 
+  const data = response?.data ?? []
   const columns = getTaskColumns({ onEdit: handleEdit, onDelete: handleDelete })
 
   const table = useReactTable({
-    data: tasks,
+    data,
     columns,
     state: { sorting, columnFilters, columnVisibility, columnOrder, rowSelection },
     onSortingChange: setSorting,
@@ -103,6 +93,7 @@ export function TasksCrudTable() {
         <Button
           size='sm'
           className='ml-2'
+          disabled={isLoading}
           onClick={() => { setEditingTask(undefined); setDialogOpen(true) }}
         >
           <Plus className='mr-1 h-4 w-4' /> Add Task

package/templates/template-vite/src/features/tasks/hooks/use-tasks.ts

@@ -0,0 +1,61 @@
+import { useMutation, useQuery, useQueryClient } from '@tanstack/react-query'
+import { toast } from 'sonner'
+import { tasksApi, type CreateTaskPayload, type UpdateTaskPayload, type TaskListParams } from '../services/tasks-api'
+
+export const TASK_QUERY_KEY = 'tasks'
+
+/** Fetch paginated task list */
+export function useTasks(params?: TaskListParams) {
+  return useQuery({
+    queryKey: [TASK_QUERY_KEY, params],
+    queryFn: () => tasksApi.list(params),
+  })
+}
+
+/** Fetch single task by id */
+export function useTask(id: string) {
+  return useQuery({
+    queryKey: [TASK_QUERY_KEY, id],
+    queryFn: () => tasksApi.getById(id),
+    enabled: !!id,
+  })
+}
+
+/** Create a new task */
+export function useCreateTask() {
+  const queryClient = useQueryClient()
+  return useMutation({
+    mutationFn: (data: CreateTaskPayload) => tasksApi.create(data),
+    onSuccess: () => {
+      queryClient.invalidateQueries({ queryKey: [TASK_QUERY_KEY] })
+      toast.success('Task created')
+    },
+    onError: () => toast.error('Failed to create task'),
+  })
+}
+
+/** Update an existing task */
+export function useUpdateTask() {
+  const queryClient = useQueryClient()
+  return useMutation({
+    mutationFn: ({ id, data }: { id: string; data: UpdateTaskPayload }) => tasksApi.update(id, data),
+    onSuccess: () => {
+      queryClient.invalidateQueries({ queryKey: [TASK_QUERY_KEY] })
+      toast.success('Task updated')
+    },
+    onError: () => toast.error('Failed to update task'),
+  })
+}
+
+/** Delete a task by id */
+export function useDeleteTask() {
+  const queryClient = useQueryClient()
+  return useMutation({
+    mutationFn: (id: string) => tasksApi.delete(id),
+    onSuccess: () => {
+      queryClient.invalidateQueries({ queryKey: [TASK_QUERY_KEY] })
+      toast.success('Task deleted')
+    },
+    onError: () => toast.error('Failed to delete task'),
+  })
+}

package/templates/template-vite/src/features/tasks/services/tasks-api.ts

@@ -0,0 +1,32 @@
+import apiClient from '@/lib/api-client'
+import type { PaginatedResponse } from '@/types'
+import type { Task } from '../types/task'
+
+export interface TaskListParams {
+  page?: number
+  limit?: number
+  search?: string
+  status?: string
+  priority?: string
+}
+
+export type CreateTaskPayload = Omit<Task, 'id' | 'createdAt'>
+export type UpdateTaskPayload = Partial<CreateTaskPayload>
+
+/** Raw API calls for the tasks resource — always use hooks (use-tasks.ts) in components */
+export const tasksApi = {
+  list: (params?: TaskListParams): Promise<PaginatedResponse<Task>> =>
+    apiClient.get('/tasks', { params }).then((r) => r.data),
+
+  getById: (id: string): Promise<Task> =>
+    apiClient.get(`/tasks/${id}`).then((r) => r.data),
+
+  create: (data: CreateTaskPayload): Promise<Task> =>
+    apiClient.post('/tasks', data).then((r) => r.data),
+
+  update: (id: string, data: UpdateTaskPayload): Promise<Task> =>
+    apiClient.put(`/tasks/${id}`, data).then((r) => r.data),
+
+  delete: (id: string): Promise<void> =>
+    apiClient.delete(`/tasks/${id}`).then((r) => r.data),
+}

package/templates/template-vite/src/features/users/components/users-table.tsx

@@ -17,13 +17,13 @@ import { PlusCircle } from 'lucide-react'
 import { Button } from '@/components/ui/button'
 import { DataTable } from '@/components/data-table/data-table'
 import { DataTableToolbar } from '@/components/data-table/data-table-toolbar'
-import { mockUsers } from '../data/users-mock-data'
+import { useUsers, useCreateUser, useUpdateUser, useDeleteUser } from '../hooks/use-users'
 import { getUsersTableColumns } from './users-table-columns'
 import { UserFormDialog } from './user-form-dialog'
 import { UserDeleteConfirmationDialog } from './user-delete-confirmation-dialog'
 import type { User } from '../types/user'
+import type { CreateUserPayload, UpdateUserPayload } from '../services/users-api'
 
-/** Filter options for role and status faceted filters */
 const roleFilterOptions = [
   { label: 'Admin', value: 'admin' },
   { label: 'Manager', value: 'manager' },
@@ -42,57 +42,40 @@ const toolbarFilters = [
 ]
 
 export function UsersTable() {
-  const [data, setData] = useState<User[]>(mockUsers)
+  const { data: response, isLoading } = useUsers()
+  const createUser = useCreateUser()
+  const updateUser = useUpdateUser()
+  const deleteUser = useDeleteUser()
+
   const [sorting, setSorting] = useState<SortingState>([])
   const [columnFilters, setColumnFilters] = useState<ColumnFiltersState>([])
   const [columnVisibility, setColumnVisibility] = useState<VisibilityState>({})
   const [columnOrder, setColumnOrder] = useState<ColumnOrderState>([])
   const [rowSelection, setRowSelection] = useState({})
-
-  // Dialog state
   const [formDialogOpen, setFormDialogOpen] = useState(false)
   const [deleteDialogOpen, setDeleteDialogOpen] = useState(false)
   const [selectedUser, setSelectedUser] = useState<User | null>(null)
 
-  const handleEdit = (user: User) => {
-    setSelectedUser(user)
-    setFormDialogOpen(true)
-  }
-
-  const handleDelete = (user: User) => {
-    setSelectedUser(user)
-    setDeleteDialogOpen(true)
-  }
-
-  const handleAddNew = () => {
-    setSelectedUser(null)
-    setFormDialogOpen(true)
-  }
+  const handleEdit = (user: User) => { setSelectedUser(user); setFormDialogOpen(true) }
+  const handleDelete = (user: User) => { setSelectedUser(user); setDeleteDialogOpen(true) }
+  const handleAddNew = () => { setSelectedUser(null); setFormDialogOpen(true) }
 
   const handleFormSubmit = (values: Omit<User, 'id' | 'createdAt'>) => {
     if (selectedUser) {
-      // Edit existing user
-      setData((prev) => prev.map((u) => (u.id === selectedUser.id ? { ...u, ...values } : u)))
+      updateUser.mutate({ id: selectedUser.id, data: values as UpdateUserPayload })
     } else {
-      // Add new user
-      const newUser: User = {
-        ...values,
-        id: String(Date.now()),
-        createdAt: new Date().toISOString().split('T')[0],
-      }
-      setData((prev) => [newUser, ...prev])
+      createUser.mutate(values as CreateUserPayload)
     }
     setFormDialogOpen(false)
   }
 
   const handleConfirmDelete = () => {
-    if (selectedUser) {
-      setData((prev) => prev.filter((u) => u.id !== selectedUser.id))
-    }
+    if (selectedUser) deleteUser.mutate(selectedUser.id)
     setDeleteDialogOpen(false)
     setSelectedUser(null)
   }
 
+  const data = response?.data ?? []
   const columns = getUsersTableColumns({ onEdit: handleEdit, onDelete: handleDelete })
 
   const table = useReactTable({
@@ -121,7 +104,7 @@ export function UsersTable() {
           searchPlaceholder='Search users...'
           filters={toolbarFilters}
         />
-        <Button size='sm' className='ml-4' onClick={handleAddNew}>
+        <Button size='sm' className='ml-4' onClick={handleAddNew} disabled={isLoading}>
           <PlusCircle className='mr-2 h-4 w-4' />
           Add User
         </Button>

package/templates/template-vite/src/features/users/hooks/use-users.ts

@@ -0,0 +1,61 @@
+import { useMutation, useQuery, useQueryClient } from '@tanstack/react-query'
+import { toast } from 'sonner'
+import { usersApi, type CreateUserPayload, type UpdateUserPayload, type UserListParams } from '../services/users-api'
+
+export const USER_QUERY_KEY = 'users'
+
+/** Fetch paginated user list */
+export function useUsers(params?: UserListParams) {
+  return useQuery({
+    queryKey: [USER_QUERY_KEY, params],
+    queryFn: () => usersApi.list(params),
+  })
+}
+
+/** Fetch single user by id */
+export function useUser(id: string) {
+  return useQuery({
+    queryKey: [USER_QUERY_KEY, id],
+    queryFn: () => usersApi.getById(id),
+    enabled: !!id,
+  })
+}
+
+/** Create a new user */
+export function useCreateUser() {
+  const queryClient = useQueryClient()
+  return useMutation({
+    mutationFn: (data: CreateUserPayload) => usersApi.create(data),
+    onSuccess: () => {
+      queryClient.invalidateQueries({ queryKey: [USER_QUERY_KEY] })
+      toast.success('User created')
+    },
+    onError: () => toast.error('Failed to create user'),
+  })
+}
+
+/** Update an existing user */
+export function useUpdateUser() {
+  const queryClient = useQueryClient()
+  return useMutation({
+    mutationFn: ({ id, data }: { id: string; data: UpdateUserPayload }) => usersApi.update(id, data),
+    onSuccess: () => {
+      queryClient.invalidateQueries({ queryKey: [USER_QUERY_KEY] })
+      toast.success('User updated')
+    },
+    onError: () => toast.error('Failed to update user'),
+  })
+}
+
+/** Delete a user by id */
+export function useDeleteUser() {
+  const queryClient = useQueryClient()
+  return useMutation({
+    mutationFn: (id: string) => usersApi.delete(id),
+    onSuccess: () => {
+      queryClient.invalidateQueries({ queryKey: [USER_QUERY_KEY] })
+      toast.success('User deleted')
+    },
+    onError: () => toast.error('Failed to delete user'),
+  })
+}

package/templates/template-vite/src/features/users/services/users-api.ts

@@ -0,0 +1,32 @@
+import apiClient from '@/lib/api-client'
+import type { PaginatedResponse } from '@/types'
+import type { User } from '../types/user'
+
+export interface UserListParams {
+  page?: number
+  limit?: number
+  search?: string
+  role?: string
+  status?: string
+}
+
+export type CreateUserPayload = Omit<User, 'id' | 'createdAt'>
+export type UpdateUserPayload = Partial<CreateUserPayload>
+
+/** Raw API calls for the users resource — always use hooks (use-users.ts) in components */
+export const usersApi = {
+  list: (params?: UserListParams): Promise<PaginatedResponse<User>> =>
+    apiClient.get('/users', { params }).then((r) => r.data),
+
+  getById: (id: string): Promise<User> =>
+    apiClient.get(`/users/${id}`).then((r) => r.data),
+
+  create: (data: CreateUserPayload): Promise<User> =>
+    apiClient.post('/users', data).then((r) => r.data),
+
+  update: (id: string, data: UpdateUserPayload): Promise<User> =>
+    apiClient.put(`/users/${id}`, data).then((r) => r.data),
+
+  delete: (id: string): Promise<void> =>
+    apiClient.delete(`/users/${id}`).then((r) => r.data),
+}

package/templates/template-vite/src/types/index.ts

@@ -1,3 +1,10 @@
+/** Generic API response wrapper from backend */
+export interface ApiResponse<T> {
+  data: T
+  message: string
+  success: boolean
+}
+
 /** Generic paginated API response */
 export interface PaginatedResponse<T> {
   data: T[]