@devmunna/agent-skillkit 0.1.0

package/skills/react-feature-arch/SKILL.md

@@ -0,0 +1,208 @@
+---
+name: react-feature-arch
+version: 2.0.0
+description: >
+  Use this skill for any React project task: component design, hooks, state management, API integration, routing, forms, or folder structure. Triggers: "React component", "custom hook", "manage state", "fetch data", "React Router", "Zustand store", "TanStack Query", "form validation", "feature architecture", "React 19", "useActionState", "useOptimistic".
+stack: [react, typescript, vite]
+depends: []
+---
+
+# React 19 — Production Feature Architecture
+
+**Version target:** React 19 · React Router v7 · TanStack Query v5 · Zustand v5 · Vite 6 · TypeScript 5 · Zod v4
+
+---
+
+## Tech Stack
+
+| Layer | Package |
+|---|---|
+| UI | react v19 + react-dom v19 |
+| Routing | react-router v7 |
+| Server state | @tanstack/react-query v5 |
+| Global UI state | zustand v5 |
+| Forms | react-hook-form v7 + @hookform/resolvers |
+| Validation | zod v4 |
+| HTTP | axios v1 |
+| Build | vite v6 + @vitejs/plugin-react |
+| Language | TypeScript 5 |
+
+---
+
+## Feature Folder Structure
+
+```
+src/
+├── app/
+│   ├── App.tsx
+│   ├── router.tsx               # createBrowserRouter — all routes
+│   └── providers.tsx            # QueryClientProvider, Suspense, ErrorBoundary
+├── features/                    # One folder per domain
+│   └── {feature}/
+│       ├── {feature}.page.tsx   # Route component — layout + composition only
+│       ├── {feature}.api.ts     # Axios API calls (all HTTP here)
+│       ├── {feature}.hooks.ts   # TanStack Query hooks (useQuery, useMutation)
+│       ├── {feature}.schema.ts  # Zod schemas + derived TypeScript types
+│       ├── components/          # Feature-specific UI components
+│       │   ├── {Feature}List.tsx
+│       │   └── {Feature}Form.tsx
+│       └── index.ts             # Public barrel export
+├── components/
+│   ├── ui/                      # Shared primitive components
+│   └── layout/                  # Layout + ProtectedRoute
+├── lib/
+│   ├── axios.ts                 # Axios instance + interceptors
+│   └── query-client.ts          # TanStack QueryClient singleton
+├── store/                       # Zustand stores (UI state only)
+│   ├── auth.store.ts
+│   └── ui.store.ts
+├── types/                       # Global TypeScript types
+└── utils/                       # Pure utility functions
+```
+
+**Rules:**
+- Import from feature barrels (`@/features/users`), never deep into another feature's internals
+- Page components own data-fetching via hooks; they compose child components and pass data down
+- All HTTP calls live in `{feature}.api.ts` — never call axios directly in hooks or components
+- Zod schemas in `{feature}.schema.ts` — TypeScript types derived with `z.infer<>`, shared by forms and API
+
+---
+
+## React 19 — New Hooks
+
+### useActionState — form actions with pending state
+```tsx
+import { useActionState } from 'react';
+import { createUserSchema } from './users.schema';
+import { usersApi } from './users.api';
+
+async function submitAction(_prev: any, formData: FormData) {
+  const result = createUserSchema.safeParse({
+    name:  formData.get('name'),
+    email: formData.get('email'),
+  });
+  if (!result.success) return { error: result.error.issues[0].message };
+  try {
+    await usersApi.create(result.data);
+    return { success: true };
+  } catch (err: any) {
+    return { error: err.message ?? 'Failed' };
+  }
+}
+
+export function CreateUserForm() {
+  const [state, formAction, isPending] = useActionState(submitAction, null);
+
+  return (
+    <form action={formAction}>
+      <input name="name" required />
+      <input name="email" type="email" required />
+      {state?.error && <p className="error">{state.error}</p>}
+      <button type="submit" disabled={isPending}>
+        {isPending ? 'Creating...' : 'Create'}
+      </button>
+    </form>
+  );
+}
+```
+
+### useOptimistic — optimistic UI
+```tsx
+import { useOptimistic, useTransition } from 'react';
+
+export function TodoList({ todos, onAdd }: { todos: Todo[]; onAdd: (t: Todo) => Promise<void> }) {
+  const [optimisticTodos, addOptimistic] = useOptimistic(
+    todos,
+    (state, newTodo: Todo) => [...state, { ...newTodo, pending: true }],
+  );
+  const [, startTransition] = useTransition();
+
+  const handleAdd = (title: string) => {
+    startTransition(async () => {
+      addOptimistic({ id: 'temp', title, done: false });
+      await onAdd({ id: 'temp', title, done: false });
+    });
+  };
+
+  return <ul>{optimisticTodos.map(t => <li key={t.id}>{t.title}</li>)}</ul>;
+}
+```
+
+### use() — read Context without useContext
+```tsx
+import { use } from 'react';
+import { ThemeContext } from '@/app/providers';
+
+export function ThemedCard({ children }: { children: React.ReactNode }) {
+  const theme = use(ThemeContext);   // replaces useContext(ThemeContext)
+  return <div className={`card-${theme}`}>{children}</div>;
+}
+```
+
+---
+
+## Component Rules
+
+- Function components only — no class components
+- Named exports preferred over default (better refactoring + tree-shaking)
+- Single responsibility: one component = one visual concern
+- Presentation components receive data via props — no direct API calls or store access
+- If a component exceeds ~100 lines, extract sub-components
+
+```tsx
+interface UserCardProps {
+  user: User;
+  onDelete: (id: string) => void;
+  isDeleting?: boolean;
+}
+
+export function UserCard({ user, onDelete, isDeleting = false }: UserCardProps) {
+  return (
+    <div className="card">
+      <h3>{user.name}</h3>
+      <p>{user.email}</p>
+      <button onClick={() => onDelete(user.id)} disabled={isDeleting}>
+        {isDeleting ? 'Deleting...' : 'Delete'}
+      </button>
+    </div>
+  );
+}
+```
+
+---
+
+## State Management Strategy
+
+| State type | Tool |
+|---|---|
+| Server data (API responses) | TanStack Query v5 |
+| Global UI (auth session, theme, sidebar) | Zustand v5 |
+| Form state | React Hook Form v7 |
+| URL state (filters, pagination, tabs) | URL search params |
+| Component-local state | useState / useReducer |
+
+**Rule:** Never put API response data in Zustand. Zustand is for UI-only global state. TanStack Query owns all server state including caching, invalidation, and background refetching.
+
+---
+
+## Key Patterns
+
+- `queryOptions()` helper for reusable, type-safe query definitions
+- Mutations call `queryClient.invalidateQueries` on success to refresh stale data
+- Axios interceptors set auth header from Zustand store + handle 401 globally
+- `useShallow` from Zustand when selecting multiple fields to prevent extra re-renders
+- Always `select` in `useQuery` to narrow returned shape when only part of data is needed
+- Lazy-load route components: `const UsersPage = lazy(() => import('./users.page'))`
+
+---
+
+## Core References
+
+| Topic | File |
+|---|---|
+| Axios instance + feature API files | `references/api-layer.md` |
+| TanStack Query v5 — queryOptions, hooks, mutations | `references/data-fetching.md` |
+| Zustand v5 — auth store, UI store | `references/state-management.md` |
+| React Hook Form + Zod v4 forms | `references/forms.md` |
+| React Router v7 — createBrowserRouter, ProtectedRoute | `references/routing.md` |
+| Component patterns + React 19 hooks | `references/components.md` |

package/skills/react-feature-arch/references/api-layer.md

@@ -0,0 +1,110 @@
+# API Layer Reference
+
+All HTTP calls live in `{feature}.api.ts`. Never import axios directly in hooks or components.
+
+---
+
+## src/lib/axios.ts — Axios Instance
+
+```ts
+import axios from 'axios';
+import { useAuthStore } from '@/store/auth.store';
+
+export const apiClient = axios.create({
+  baseURL: import.meta.env.VITE_API_URL,
+  headers: { 'Content-Type': 'application/json' },
+  timeout: 10_000,
+});
+
+// Attach Bearer token to every request
+apiClient.interceptors.request.use((config) => {
+  const token = useAuthStore.getState().token;
+  if (token) config.headers.Authorization = `Bearer ${token}`;
+  return config;
+});
+
+// Unwrap data.data + handle 401 globally
+apiClient.interceptors.response.use(
+  (res) => res.data,   // callers receive the payload directly (no res.data wrapper)
+  (err) => {
+    if (err.response?.status === 401) {
+      useAuthStore.getState().logout();
+    }
+    return Promise.reject(err.response?.data ?? err);
+  },
+);
+```
+
+---
+
+## .env
+
+```
+VITE_API_URL=http://localhost:3000/api/v1
+```
+
+---
+
+## Feature API File — {feature}.api.ts
+
+```ts
+// features/users/users.api.ts
+import { apiClient } from '@/lib/axios';
+import type { CreateUserDto, UpdateUserDto, User } from './users.schema';
+
+export interface PaginatedResponse<T> {
+  data: T[];
+  meta: {
+    total:      number;
+    page:       number;
+    limit:      number;
+    totalPages: number;
+    hasNext:    boolean;
+    hasPrev:    boolean;
+  };
+}
+
+export interface ListParams {
+  page?:   number;
+  limit?:  number;
+  search?: string;
+}
+
+export const usersApi = {
+  getAll: (params: ListParams) =>
+    apiClient.get<never, PaginatedResponse<User>>('/users', { params }),
+
+  getById: (id: string) =>
+    apiClient.get<never, User>(`/users/${id}`),
+
+  create: (data: CreateUserDto) =>
+    apiClient.post<never, User>('/users', data),
+
+  update: (id: string, data: UpdateUserDto) =>
+    apiClient.patch<never, User>(`/users/${id}`, data),
+
+  remove: (id: string) =>
+    apiClient.delete<never, void>(`/users/${id}`),
+};
+```
+
+---
+
+## Auth API
+
+```ts
+// features/auth/auth.api.ts
+import { apiClient } from '@/lib/axios';
+import type { LoginDto, RegisterDto, User } from './auth.schema';
+
+export const authApi = {
+  login: (data: LoginDto) =>
+    apiClient.post<never, { user: User; token: string }>('/auth/login', data),
+
+  register: (data: RegisterDto) =>
+    apiClient.post<never, { user: User; token: string }>('/auth/register', data),
+
+  me: () =>
+    apiClient.get<never, User>('/auth/me'),
+};
+```

package/skills/react-feature-arch/references/components.md

@@ -0,0 +1,192 @@
+# Component Patterns Reference — React 19
+
+---
+
+## Feature Component Structure
+
+```tsx
+// features/users/components/UserList.tsx
+import type { User } from '../users.schema';
+import { UserCard }  from './UserCard';
+
+interface UserListProps {
+  users:      User[];
+  onDelete?:  (id: string) => void;
+  isDeleting?: boolean;
+}
+
+export function UserList({ users, onDelete, isDeleting }: UserListProps) {
+  if (users.length === 0) return <p className="empty">No users found.</p>;
+
+  return (
+    <ul className="user-list">
+      {users.map((user) => (
+        <UserCard
+          key={user.id}
+          user={user}
+          onDelete={onDelete}
+          isDeleting={isDeleting}
+        />
+      ))}
+    </ul>
+  );
+}
+```
+
+---
+
+## Smart + Dumb Composition Pattern
+
+```tsx
+// SMART — page-level, owns data fetching
+export function UsersPage() {
+  const [page, setPage] = useState(1);
+  const { data, isLoading } = useUsers({ page, limit: 10 });
+  const { mutate: deleteUser, isPending } = useDeleteUser();
+
+  return (
+    <UserList
+      users={data?.data ?? []}
+      isLoading={isLoading}
+      onDelete={deleteUser}
+      isDeleting={isPending}
+    />
+  );
+}
+
+// DUMB — purely presentational, receives all data via props
+export function UserList({ users, isLoading, onDelete, isDeleting }: Props) {
+  if (isLoading) return <Skeleton count={5} />;
+  return users.map((u) => (
+    <UserCard key={u.id} user={u} onDelete={onDelete} isDeleting={isDeleting} />
+  ));
+}
+```
+
+---
+
+## Performance Optimization
+
+```tsx
+import { memo, useMemo, useCallback } from 'react';
+
+// Memoize expensive computation
+const sortedUsers = useMemo(
+  () => [...users].sort((a, b) => a.name.localeCompare(b.name)),
+  [users],
+);
+
+// Stabilize callback passed to memoized children
+const handleDelete = useCallback((id: string) => deleteUser(id), [deleteUser]);
+
+// Memoize leaf component that gets stable props
+export const UserCard = memo(function UserCard({ user, onDelete }: UserCardProps) {
+  return (
+    <div className="card">
+      <h3>{user.name}</h3>
+      <button onClick={() => onDelete(user.id)}>Delete</button>
+    </div>
+  );
+});
+```
+
+---
+
+## Custom Hooks
+
+```ts
+// features/auth/auth.hooks.ts
+import { useMutation }   from '@tanstack/react-query';
+import { useNavigate }   from 'react-router';
+import { useAuthStore }  from '@/store/auth.store';
+import { authApi }       from './auth.api';
+import { queryClient }   from '@/lib/query-client';
+
+export function useLogin() {
+  const login    = useAuthStore((s) => s.login);
+  const navigate = useNavigate();
+
+  return useMutation({
+    mutationFn: authApi.login,
+    onSuccess: ({ user, token }) => {
+      login(user, token);
+      navigate('/dashboard');
+    },
+  });
+}
+
+export function useLogout() {
+  const logout   = useAuthStore((s) => s.logout);
+  const navigate = useNavigate();
+
+  return () => {
+    logout();
+    queryClient.clear();          // clear all cached server data on logout
+    navigate('/auth/login');
+  };
+}
+
+// Shared utility hook
+export function useDebounce<T>(value: T, delay: number): T {
+  const [debounced, setDebounced] = useState(value);
+
+  useEffect(() => {
+    const timer = setTimeout(() => setDebounced(value), delay);
+    return () => clearTimeout(timer);
+  }, [value, delay]);
+
+  return debounced;
+}
+```
+
+---
+
+## Error Boundary
+
+```tsx
+// components/ui/ErrorBoundary.tsx
+import { Component, type ReactNode } from 'react';
+
+interface State { hasError: boolean; message: string }
+
+export class ErrorBoundary extends Component<
+  { children: ReactNode; fallback?: ReactNode },
+  State
+> {
+  state: State = { hasError: false, message: '' };
+
+  static getDerivedStateFromError(err: Error): State {
+    return { hasError: true, message: err.message };
+  }
+
+  render() {
+    if (this.state.hasError) {
+      return this.props.fallback ?? (
+        <div className="error-boundary">
+          <h2>Something went wrong</h2>
+          <p>{this.state.message}</p>
+          <button onClick={() => this.setState({ hasError: false, message: '' })}>
+            Try again
+          </button>
+        </div>
+      );
+    }
+    return this.props.children;
+  }
+}
+```
+
+---
+
+## Feature Barrel Export (index.ts)
+
+Export only the public surface. Never export internal helpers.
+
+```ts
+// features/users/index.ts
+export { UsersPage }      from './users.page';
+export { UserList }       from './components/UserList';
+export { CreateUserForm } from './components/CreateUserForm';
+export { useUsers, useUser, useCreateUser, useDeleteUser } from './users.hooks';
+export type { User, CreateUserDto, UpdateUserDto } from './users.schema';
+```

package/skills/react-feature-arch/references/data-fetching.md

@@ -0,0 +1,198 @@
+# TanStack Query v5 Reference
+
+---
+
+## src/lib/query-client.ts
+
+```ts
+import { QueryClient } from '@tanstack/react-query';
+
+export const queryClient = new QueryClient({
+  defaultOptions: {
+    queries: {
+      staleTime:            1000 * 60 * 5, // 5 min before background refetch
+      retry:                1,
+      refetchOnWindowFocus: false,
+    },
+  },
+});
+```
+
+---
+
+## src/app/providers.tsx
+
+```tsx
+import { QueryClientProvider } from '@tanstack/react-query';
+import { ReactQueryDevtools }   from '@tanstack/react-query-devtools';
+import { queryClient }          from '@/lib/query-client';
+
+export function Providers({ children }: { children: React.ReactNode }) {
+  return (
+    <QueryClientProvider client={queryClient}>
+      {children}
+      <ReactQueryDevtools initialIsOpen={false} />
+    </QueryClientProvider>
+  );
+}
+```
+
+---
+
+## queryOptions() — Reusable Query Definitions (v5)
+
+Define query options once, reuse in `useQuery`, `useSuspenseQuery`, and `queryClient.prefetchQuery`.
+
+```ts
+// features/users/users.hooks.ts
+import {
+  queryOptions,
+  useQuery,
+  useSuspenseQuery,
+  useMutation,
+  useQueryClient,
+} from '@tanstack/react-query';
+import { usersApi, type ListParams } from './users.api';
+import type { CreateUserDto, UpdateUserDto } from './users.schema';
+
+export const userQueries = {
+  list: (params: ListParams) =>
+    queryOptions({
+      queryKey: ['users', 'list', params],
+      queryFn:  () => usersApi.getAll(params),
+    }),
+
+  detail: (id: string) =>
+    queryOptions({
+      queryKey: ['users', id],
+      queryFn:  () => usersApi.getById(id),
+      enabled:  !!id,
+    }),
+};
+```
+
+---
+
+## Hooks — List, Detail, Mutations
+
+```ts
+// List with pagination
+export function useUsers(params: ListParams) {
+  return useQuery(userQueries.list(params));
+}
+
+// Detail
+export function useUser(id: string) {
+  return useQuery(userQueries.detail(id));
+}
+
+// Suspense variant — throws while loading, use inside <Suspense>
+export function useUserSuspense(id: string) {
+  return useSuspenseQuery(userQueries.detail(id));
+}
+
+// Create
+export function useCreateUser() {
+  const queryClient = useQueryClient();
+
+  return useMutation({
+    mutationFn: (data: CreateUserDto) => usersApi.create(data),
+    onSuccess:  () => {
+      queryClient.invalidateQueries({ queryKey: ['users'] });
+    },
+  });
+}
+
+// Update
+export function useUpdateUser() {
+  const queryClient = useQueryClient();
+
+  return useMutation({
+    mutationFn: ({ id, data }: { id: string; data: UpdateUserDto }) =>
+      usersApi.update(id, data),
+    onSuccess: (_res, { id }) => {
+      queryClient.invalidateQueries({ queryKey: ['users'] });
+      queryClient.invalidateQueries({ queryKey: ['users', id] });
+    },
+  });
+}
+
+// Delete with optimistic update
+export function useDeleteUser() {
+  const queryClient = useQueryClient();
+
+  return useMutation({
+    mutationFn: (id: string) => usersApi.remove(id),
+    onMutate: async (id) => {
+      await queryClient.cancelQueries({ queryKey: ['users'] });
+      const snapshot = queryClient.getQueryData(userQueries.list({ page: 1, limit: 10 }).queryKey);
+      // Optimistically remove from list
+      queryClient.setQueriesData({ queryKey: ['users', 'list'] }, (old: any) =>
+        old ? { ...old, data: old.data.filter((u: any) => u.id !== id) } : old,
+      );
+      return { snapshot };
+    },
+    onError: (_err, _id, context) => {
+      if (context?.snapshot) {
+        queryClient.setQueryData(
+          userQueries.list({ page: 1, limit: 10 }).queryKey,
+          context.snapshot,
+        );
+      }
+    },
+    onSettled: () => {
+      queryClient.invalidateQueries({ queryKey: ['users'] });
+    },
+  });
+}
+```
+
+---
+
+## Usage in Page Component
+
+```tsx
+// features/users/users.page.tsx
+import { useState } from 'react';
+import { useUsers, useDeleteUser } from './users.hooks';
+import { UserList }   from './components/UserList';
+import { Pagination } from '@/components/ui/Pagination';
+
+export function UsersPage() {
+  const [page, setPage] = useState(1);
+  const { data, isLoading, error } = useUsers({ page, limit: 10 });
+  const { mutate: deleteUser, isPending: isDeleting } = useDeleteUser();
+
+  if (isLoading) return <div>Loading...</div>;
+  if (error)     return <div>Error: {(error as any).message}</div>;
+
+  return (
+    <>
+      <UserList
+        users={data!.data}
+        onDelete={deleteUser}
+        isDeleting={isDeleting}
+      />
+      <Pagination meta={data!.meta} onPageChange={setPage} />
+    </>
+  );
+}
+```
+
+---
+
+## Prefetching (router loaders)
+
+```ts
+// Prefetch in router loader for instant navigation
+import { queryClient } from '@/lib/query-client';
+
+const router = createBrowserRouter([
+  {
+    path: '/users/:id',
+    loader: ({ params }) =>
+      queryClient.ensureQueryData(userQueries.detail(params.id!)),
+    element: <UserDetailPage />,
+  },
+]);
+```