@react-vault/create-app 0.1.0

package/templates/tanstack-query/.claude/skills/constants-organization/references/query-key-factories.md

@@ -0,0 +1,129 @@
+# queryKey factory pattern
+
+QueryKeys are TanStack Query's primary cache identifier. They MUST be:
+
+- Stable: same logical query → same key shape
+- Discoverable: cache invalidation should be easy to write
+- Type-safe: keys derived from a factory, not hand-typed
+
+## Anti-pattern: inline arrays
+
+```tsx
+// ❌ Don't do this:
+useQuery({ queryKey: ['kyc', id], queryFn: () => getKyc(id) });
+
+// ❌ Or this:
+queryClient.invalidateQueries({ queryKey: ['kyc'] });
+```
+
+Problems:
+
+- Renaming the feature requires grep across the whole codebase
+- Easy to typo the queryKey, causing silent cache misses
+- Filter shapes embedded in keys aren't reused
+
+## Pattern: factory objects
+
+```ts
+// src/utils/constants/queryKeys.ts
+export const kycKeys = {
+  all: ['kyc'] as const,
+  lists: () => [...kycKeys.all, 'list'] as const,
+  list: (filters?: KycFilters) => [...kycKeys.lists(), filters] as const,
+  details: () => [...kycKeys.all, 'detail'] as const,
+  detail: (id: string) => [...kycKeys.details(), id] as const,
+};
+```
+
+Usage:
+
+```tsx
+useQuery({
+  queryKey: kycKeys.detail(id),
+  queryFn: () => getKyc(id),
+});
+```
+
+## Invalidation matrix
+
+| Goal                                  | Code                                                                               |
+| ------------------------------------- | ---------------------------------------------------------------------------------- |
+| Invalidate everything for the feature | `queryClient.invalidateQueries({ queryKey: kycKeys.all })`                         |
+| Invalidate all lists (any filter)     | `queryClient.invalidateQueries({ queryKey: kycKeys.lists() })`                     |
+| Invalidate one specific list          | `queryClient.invalidateQueries({ queryKey: kycKeys.list({ status: 'pending' }) })` |
+| Invalidate all details                | `queryClient.invalidateQueries({ queryKey: kycKeys.details() })`                   |
+| Invalidate one record                 | `queryClient.invalidateQueries({ queryKey: kycKeys.detail(id) })`                  |
+
+TanStack Query matches by **prefix** — `kycKeys.all` invalidates everything that starts with `['kyc']`.
+
+## Pattern: after a mutation
+
+```tsx
+const queryClient = useQueryClient();
+
+const submit = useMutation({
+  mutationFn: submitKyc,
+  onSuccess: (newRecord) => {
+    // Drop the lists cache so the next list query refetches
+    queryClient.invalidateQueries({ queryKey: kycKeys.lists() });
+    // Optionally pre-fill the detail cache so navigating to it is instant
+    queryClient.setQueryData(kycKeys.detail(newRecord.id), newRecord);
+  },
+});
+```
+
+## Pattern: cross-feature invalidation
+
+```tsx
+const submit = useMutation({
+  mutationFn: submitKyc,
+  onSuccess: () => {
+    queryClient.invalidateQueries({ queryKey: kycKeys.all });
+    queryClient.invalidateQueries({ queryKey: userKeys.detail(userId) }); // KYC changes affect user profile
+  },
+});
+```
+
+For complex graphs, consider a small middleware-like wrapper:
+
+```ts
+// src/services/invalidations.ts
+export const invalidationsAfter = {
+  kycSubmit: (qc: QueryClient, userId: string) => {
+    qc.invalidateQueries({ queryKey: kycKeys.all });
+    qc.invalidateQueries({ queryKey: userKeys.detail(userId) });
+  },
+  // ... other cross-feature invalidation recipes
+};
+
+// Then in components:
+const submit = useMutation({
+  mutationFn: submitKyc,
+  onSuccess: () => invalidationsAfter.kycSubmit(queryClient, currentUserId),
+});
+```
+
+## Anti-pattern: keys in the wrong order
+
+The order matters — TanStack Query treats the array as a prefix. Always put the most general element first:
+
+```ts
+// ✅ Good
+list: (filters) => ['kyc', 'list', filters] as const;
+
+// ❌ Bad — can't invalidate "all kyc" without listing every filter
+list: (filters) => [filters, 'kyc', 'list'] as const;
+```
+
+## Logout: nuke the cache
+
+```ts
+import { kycKeys } from '@/utils/constants/queryKeys';
+
+function logout() {
+  // ... clear auth
+  queryClient.clear(); // wipes EVERYTHING (preferred on logout)
+  // alternative — selective:
+  // queryClient.removeQueries({ queryKey: kycKeys.all });
+}
+```

package/templates/tanstack-query/.claude/skills/query-client-setup/SKILL.md

@@ -0,0 +1,165 @@
+---
+name: query-client-setup
+description: Configure the TanStack QueryClient — defaults, retry policy, refetch behaviour, optional global error handlers, devtools. Use when setting up the QueryClient for the first time, adjusting retry / staleTime / refetch behaviour, adding a global error handler, or wiring devtools.
+---
+
+# QueryClient Setup
+
+`src/api/queryClient.ts` exports a single `QueryClient` instance with BFSI-friendly defaults. It's mounted via `<QueryClientProvider>` in `src/app/App.tsx`.
+
+## File map
+
+```
+src/api/
+├── axiosInstance.ts    single axios for all services
+├── http.ts             typed GET/POST/PUT/PATCH/DELETE helpers
+└── queryClient.ts      QueryClient with defaultOptions
+src/app/
+└── App.tsx             wraps in <QueryClientProvider client={queryClient}>
+```
+
+## Default config (what the scaffolder ships)
+
+```ts
+import { QueryClient } from '@tanstack/react-query';
+
+export const queryClient = new QueryClient({
+  defaultOptions: {
+    queries: {
+      staleTime: 30_000, // 30s — minimise thrash, refetch when stale
+      gcTime: 5 * 60_000, // 5min — keep in cache after unsubscribed
+      retry: (failureCount, error) => {
+        const status = (error as { status?: number })?.status;
+        // Don't retry 4xx (except 408/429)
+        if (status && status >= 400 && status < 500 && status !== 408 && status !== 429) {
+          return false;
+        }
+        return failureCount < 2;
+      },
+      refetchOnWindowFocus: false, // BFSI: don't refetch on tab switch
+    },
+    mutations: {
+      retry: false, // Never auto-retry mutations
+    },
+  },
+});
+```
+
+## Why these defaults
+
+| Setting                       | Choice            | Reason                                                                                                              |
+| ----------------------------- | ----------------- | ------------------------------------------------------------------------------------------------------------------- |
+| `staleTime: 30_000`           | 30 seconds        | Prevents thrash from rapid component remounts; long enough that two users on the same screen don't both hit the API |
+| `gcTime: 5 * 60_000`          | 5 minutes         | Keeps caches around when user navigates back; cleared on logout via `queryClient.clear()`                           |
+| `retry: 4xx → no`             | 4xx → no, 5xx → 2 | 4xx is a contract issue — retrying won't help. 5xx might be transient.                                              |
+| `refetchOnWindowFocus: false` | off               | BFSI users tab away and back; surprise refetches lose draft state                                                   |
+| `mutations.retry: false`      | never retry       | Mutations have side effects. Use idempotency-key + explicit user retry.                                             |
+
+## Workflow — adjusting defaults
+
+Don't override these in component-level `useQuery` calls unless you have a specific reason. Override the default once in `queryClient.ts`:
+
+```ts
+defaultOptions: {
+  queries: {
+    staleTime: 60_000,    // change to 60s
+    // ...
+  },
+},
+```
+
+For a per-feature override:
+
+```tsx
+const { data } = useQuery({
+  queryKey: kycKeys.list(filters),
+  queryFn: () => getKycList(filters),
+  staleTime: 0, // always refetch on mount (audit-critical list)
+});
+```
+
+## Wiring into the app
+
+`src/app/App.tsx` (variant overlay):
+
+```tsx
+import { QueryClientProvider } from '@tanstack/react-query';
+import { ReactQueryDevtools } from '@tanstack/react-query-devtools';
+import { BrowserRouter } from 'react-router-dom';
+import { ErrorBoundary } from '../shared/ErrorBoundary';
+import { AppRoutes } from '../routes';
+import { queryClient } from '../api/queryClient';
+
+export function App(): JSX.Element {
+  return (
+    <ErrorBoundary>
+      <QueryClientProvider client={queryClient}>
+        <BrowserRouter>
+          <AppRoutes />
+        </BrowserRouter>
+        {import.meta.env.DEV && <ReactQueryDevtools initialIsOpen={false} />}
+      </QueryClientProvider>
+    </ErrorBoundary>
+  );
+}
+```
+
+Devtools render only in dev (gated by `import.meta.env.DEV`).
+
+## Global error handlers (optional)
+
+For a "catch all unhandled mutation errors" toast, use a `MutationCache`:
+
+```ts
+import { QueryClient, MutationCache } from '@tanstack/react-query';
+import { toast } from 'sonner';
+import { toSafeView } from '@<scope>/core/compliance';
+import type { ApiError } from '@<scope>/core/http';
+import i18n from '@/i18n/i18n';
+
+export const queryClient = new QueryClient({
+  mutationCache: new MutationCache({
+    onError: (error, _vars, _ctx, mutation) => {
+      if (mutation.options.onError) return; // skip if per-mutation handler set
+      const view = toSafeView(error as ApiError, i18n.t);
+      toast.error(view.title, { description: view.description });
+    },
+  }),
+  defaultOptions: {
+    /* ... */
+  },
+});
+```
+
+See [`references/global-handlers.md`](references/global-handlers.md) for QueryCache + MutationCache patterns.
+
+## Conventions enforced
+
+- ❌ NEVER create multiple `QueryClient` instances — there must be exactly one for the app.
+- ❌ NEVER set `refetchOnWindowFocus: true` globally (BFSI default is off).
+- ❌ NEVER enable `mutations.retry > 0` globally — mutations have side effects.
+- ❌ NEVER render `<ReactQueryDevtools>` in production builds — gate on `import.meta.env.DEV`.
+- ✅ `<QueryClientProvider>` wraps the WHOLE app (above the router, below ErrorBoundary).
+- ✅ Per-query overrides go in the `useQuery` call, not the QueryClient config.
+- ✅ On logout: `queryClient.clear()` after `clearAuthToken()`.
+
+## Logout sequence
+
+```ts
+import { clearAuthToken } from '@<scope>/core/http';
+import { queryClient } from '@/api/queryClient';
+import axiosInstance from '@/api/axiosInstance';
+
+export function logout() {
+  clearAuthToken(axiosInstance); // drop the auth header
+  queryClient.clear(); // wipe all cached server data
+  navigate('/login');
+}
+```
+
+`queryClient.clear()` removes all cached queries + in-flight fetches. Without it, a re-login on the same browser sees stale data for a flash before refetch.
+
+## References
+
+- [`references/global-handlers.md`](references/global-handlers.md) — QueryCache.onError + MutationCache.onError patterns
+- [`references/devtools.md`](references/devtools.md) — using ReactQueryDevtools effectively

package/templates/tanstack-query/.claude/skills/query-client-setup/references/devtools.md

@@ -0,0 +1,67 @@
+# Using ReactQueryDevtools effectively
+
+The devtools panel is the single most useful tool for debugging TanStack Query behaviour. Render it conditionally so it never reaches production bundles.
+
+## Setup
+
+```tsx
+import { ReactQueryDevtools } from '@tanstack/react-query-devtools';
+
+<QueryClientProvider client={queryClient}>
+  {/* app */}
+  {import.meta.env.DEV && <ReactQueryDevtools initialIsOpen={false} />}
+</QueryClientProvider>;
+```
+
+`@tanstack/react-query-devtools` is in `devDependencies` and Vite tree-shakes it out of the production bundle as long as the import is gated behind `import.meta.env.DEV`. Confirm with `pnpm build && grep -r 'ReactQueryDevtools' dist/`.
+
+## Debugging workflow
+
+When something feels wrong with caching/refetching:
+
+1. **Open devtools** (icon in bottom-right corner).
+2. **Find the queryKey** — search the list for your feature (e.g. `kyc`).
+3. **Inspect the state**:
+   - `fetchStatus: idle/fetching/paused` — is it actually fetching?
+   - `status: pending/success/error` — what's the last result?
+   - `data` — the parsed response (or `undefined`)
+   - `error` — the ApiError instance
+4. **Check observers** — which components are subscribed? If 0, the query won't refetch on stale.
+5. **Manual invalidate** — click "Invalidate" to force-refetch and see if the issue is invalidation logic vs the network call.
+6. **Time travel** — switch query state to "Fresh" or "Stale" to test edge cases.
+
+## Common issues + how the devtools reveal them
+
+| Symptom                               | What devtools shows                                  | Fix                                                            |
+| ------------------------------------- | ---------------------------------------------------- | -------------------------------------------------------------- |
+| List doesn't refetch after a mutation | List query is "Fresh" not "Stale" after the mutation | Missing `invalidateQueries` in mutation's `onSuccess`          |
+| Query won't fire                      | `fetchStatus: paused`, `enabled: false`              | Some upstream variable is undefined; check the `enabled:` flag |
+| Two components show different data    | They have different queryKey shapes                  | Normalise queryKey via a factory                               |
+| Cache size grows forever              | Many entries with `observers: 0`                     | `gcTime` too long; lower it                                    |
+| Mutation seems to retry               | Multiple "pending" entries                           | Check `mutations.retry` is `false`                             |
+
+## Don't ship devtools to prod
+
+Risk: devtools expose query payloads, including PII. Even though they only render `import.meta.env.DEV`, double-check:
+
+```bash
+pnpm build
+grep -r 'ReactQueryDevtools' dist/        # should be empty
+grep -r 'TanStack Query' dist/             # should be empty
+```
+
+If you see hits, the gating is wrong — ReactQueryDevtools is in the production bundle.
+
+## Alternative for staging
+
+If you need devtools-like inspection in staging (not full prod), add a feature flag:
+
+```tsx
+{
+  (import.meta.env.DEV || env.VITE_ENABLE_QUERY_DEVTOOLS === 'true') && (
+    <ReactQueryDevtools initialIsOpen={false} />
+  );
+}
+```
+
+NEVER set `VITE_ENABLE_QUERY_DEVTOOLS=true` in production — it ships the devtools.

package/templates/tanstack-query/.claude/skills/query-client-setup/references/global-handlers.md

@@ -0,0 +1,94 @@
+# Global QueryCache / MutationCache handlers
+
+For cross-cutting concerns (every-error toast, every-success audit), use the cache-level callbacks instead of repeating `onError` in every component.
+
+## When to use cache-level vs per-call
+
+| Concern                          | Where                                     | Why                                                                     |
+| -------------------------------- | ----------------------------------------- | ----------------------------------------------------------------------- |
+| Default error toast              | `MutationCache.onError`                   | DRY — every component without its own onError gets it                   |
+| Per-mutation audit event         | `useAuditedMutation` wrapper              | Audit needs event name, target, etc. — too granular for cache-level     |
+| Global "session expired" handler | `axios.onUnauthorized` (in `createAxios`) | 401 is handled before the error reaches React; no cache callback needed |
+| Logging all query failures       | `QueryCache.onError`                      | Observability — fire-and-forget telemetry                               |
+| Per-query field error mapping    | Per-mutation `onError`                    | Field errors are component-specific (which RHF form to set them on)     |
+
+## MutationCache pattern
+
+```ts
+import { QueryClient, MutationCache } from '@tanstack/react-query';
+import { toast } from 'sonner';
+import { toSafeView } from '@<scope>/core/compliance';
+import type { ApiError } from '@<scope>/core/http';
+import i18n from '@/i18n/i18n';
+
+export const queryClient = new QueryClient({
+  mutationCache: new MutationCache({
+    onError: (error, _vars, _ctx, mutation) => {
+      // Skip if mutation defined its own onError
+      if (mutation.options.onError) return;
+
+      const apiErr = error as ApiError;
+      // Skip 401 (handled by axios.onUnauthorized)
+      if (apiErr.kind === 'unauthorized') return;
+
+      const view = toSafeView(apiErr, i18n.t);
+      toast.error(view.title, { description: view.description });
+    },
+    onSuccess: (_data, _vars, _ctx, mutation) => {
+      const successMessage = (mutation.options as { successMessage?: string }).successMessage;
+      if (successMessage) toast.success(successMessage);
+    },
+  }),
+  // ... defaultOptions
+});
+```
+
+Note: `mutation.options.onError` being set means the component has opted-in to handle the error itself. Skip the global toast to avoid double-toasting.
+
+## QueryCache pattern (rarer)
+
+```ts
+import { QueryCache } from '@tanstack/react-query';
+import * as Sentry from '@sentry/react';
+
+queryCache: new QueryCache({
+  onError: (error, query) => {
+    // Don't toast on query errors (they may fire in background)
+    // Just log to telemetry
+    Sentry.captureException(error, {
+      tags: { queryKey: JSON.stringify(query.queryKey) },
+    });
+  },
+}),
+```
+
+Don't surface query errors to UI via global toast — they fire in background and may be for unmounted components. Let the component handle its own error state via `{ error, isError } = useQuery(...)`.
+
+## Anti-patterns
+
+❌ `MutationCache.onError` that always fires even when the component has its own:
+
+```ts
+// WRONG — double-toasts
+onError: (error) => {
+  toast.error(safeMessage(error));    // fires even if component handled it
+},
+```
+
+❌ `QueryCache.onError` that toasts:
+
+```ts
+// WRONG — toasts for background refetches the user didn't trigger
+onError: (error) => toast.error(safeMessage(error)),
+```
+
+❌ Per-mutation `onError` that re-throws (TanStack catches and routes via cache):
+
+```ts
+// WRONG — onError shouldn't throw
+useMutation({
+  onError: (err) => {
+    throw err;
+  }, // breaks rollback chain
+});
+```

package/templates/tanstack-query/.claude/skills/tanstack-services/SKILL.md

@@ -0,0 +1,142 @@
+---
+name: tanstack-services
+description: Create the service layer for a feature — typed async functions that wrap the HTTP helpers (GET/POST/PUT/PATCH/DELETE) and return parsed responses. Services are hook-free and consumed by useQuery / useMutation in components. Use when adding a new feature's services, adding a new service to an existing feature, or wiring API endpoints.
+---
+
+# TanStack Services
+
+Every feature has a service file at `src/services/<feature>.ts` (or `src/features/<Feature>/service.ts`). Services are plain async functions: typed inputs in, typed parsed output out. No hooks. No React.
+
+## File map (typical feature)
+
+```
+src/features/<Feature>/
+├── service.ts          typed async functions
+├── schema.ts           Zod schemas (request + response)
+├── types.ts            inferred types from Zod
+├── containers/...      React components that call services via useQuery/useMutation
+```
+
+## Workflow — new feature service
+
+### Step 1 — Define schemas
+
+`src/features/Kyc/schema.ts`:
+
+```ts
+import { z } from 'zod';
+import { PAN_REGEX, AADHAAR_REGEX } from '@/utils/constants/regexConstants';
+
+export const kycRecordSchema = z.object({
+  id: z.string(),
+  pan: z.string().regex(PAN_REGEX),
+  aadhaar: z.string().regex(AADHAAR_REGEX),
+  status: z.enum(['pending', 'approved', 'rejected']),
+  createdAt: z.coerce.date(),
+});
+
+export const kycListResponseSchema = z.object({
+  items: z.array(kycRecordSchema),
+  total: z.number().int().nonnegative(),
+});
+
+export const kycSubmitRequestSchema = z.object({
+  pan: z.string().regex(PAN_REGEX),
+  aadhaar: z.string().regex(AADHAAR_REGEX),
+});
+```
+
+Types are inferred — never hand-write:
+
+```ts
+// types.ts
+import { z } from 'zod';
+import type { kycRecordSchema, kycListResponseSchema, kycSubmitRequestSchema } from './schema';
+
+export type IKycRecord = z.infer<typeof kycRecordSchema>;
+export type IKycListResponse = z.infer<typeof kycListResponseSchema>;
+export type IKycSubmitRequest = z.infer<typeof kycSubmitRequestSchema>;
+```
+
+### Step 2 — Write services
+
+`src/features/Kyc/service.ts`:
+
+```ts
+import { GET, POST } from '@/api/http';
+import { KYC_URLS } from '@/utils/constants/urlConstants';
+import { kycRecordSchema, kycListResponseSchema } from './schema';
+import type { IKycRecord, IKycListResponse, IKycSubmitRequest } from './types';
+
+export const getKycList = async (): Promise<IKycListResponse> => {
+  const raw = await GET<unknown>(KYC_URLS.LIST);
+  return kycListResponseSchema.parse(raw);
+};
+
+export const getKycDetail = async (id: string): Promise<IKycRecord> => {
+  const raw = await GET<unknown>(KYC_URLS.DETAIL(id));
+  return kycRecordSchema.parse(raw);
+};
+
+export const submitKyc = async (payload: IKycSubmitRequest): Promise<IKycRecord> => {
+  const raw = await POST<unknown, IKycSubmitRequest>(KYC_URLS.SUBMIT, payload);
+  return kycRecordSchema.parse(raw);
+};
+```
+
+### Step 3 — Use in components
+
+```tsx
+import { useQuery, useMutation, useQueryClient } from '@tanstack/react-query';
+import { kycKeys } from '@/utils/constants/queryKeys';
+import { getKycList, getKycDetail, submitKyc } from './service';
+
+function KycList() {
+  const { data, isLoading, error } = useQuery({
+    queryKey: kycKeys.lists(),
+    queryFn: getKycList,
+  });
+  // ...
+}
+
+function KycForm() {
+  const queryClient = useQueryClient();
+  const submit = useMutation({
+    mutationFn: submitKyc,
+    onSuccess: () => {
+      queryClient.invalidateQueries({ queryKey: kycKeys.all });
+    },
+  });
+  // ...
+}
+```
+
+## Conventions enforced
+
+- ❌ NEVER use `axios.<method>` directly — use the typed `GET<TRes, TParams>` / `POST<TRes, TReq>` helpers from `@/api/http`.
+- ❌ NEVER skip the `.parse()` step — every response goes through Zod validation at runtime.
+- ❌ NEVER inline a URL string — use `urlConstants.ts`.
+- ❌ NEVER call services without typing the response — the generic on `GET<IResponse>` is required.
+- ❌ NEVER put React hooks in service files — services are pure async functions.
+- ✅ One service file per feature; export named async functions.
+- ✅ Request types prefixed `I` (`IKycSubmitRequest`) to match service interface convention.
+- ✅ Responses parsed by Zod schemas from the same feature's `schema.ts`.
+- ✅ Use `getX` / `submitX` / `updateX` / `deleteX` naming for service functions.
+
+## Service vs hook
+
+A service is a plain function: `getKyc(id): Promise<IKycRecord>`.
+
+A hook wraps it with TanStack Query: `useQuery({ queryKey: kycKeys.detail(id), queryFn: () => getKyc(id) })`.
+
+Don't pre-bundle the hook into the service. Keep services hook-free so:
+
+- They're trivial to unit test (call them directly with mocked axios)
+- The component decides cache behaviour (staleTime, refetch, enabled, etc.)
+- The same service can power useQuery, useMutation, OR a direct call outside a component (rare but useful — e.g. in a logout flow)
+
+## References
+
+- [`references/service-cookbook.md`](references/service-cookbook.md) — list, detail, paginated, file-upload, file-download, polling examples
+- [`references/optimistic-update.md`](references/optimistic-update.md) — optimistic mutations with cache patches
+- [`references/audited-mutation.md`](references/audited-mutation.md) — wrapping useMutation to fire audit events