@baldurpan/create-ai-workflow 0.2.0

package/templates/standards/tooling/tanstack-router.md

@@ -0,0 +1,365 @@
+# TanStack Router
+
+## Core Rules
+
+- Define routes as code (or file-based) with full type inference — no string-typed paths
+- Validate all search params with Zod — typed and runtime-safe
+- Load data in route loaders, consume with `useSuspenseQuery` — eliminates loading flicker on navigation
+- Use route-level `pendingComponent` / `errorComponent` for navigation transitions; component-level `<Suspense>` / `<ErrorBoundary>` for in-page widgets
+- Auth-guard with `beforeLoad` — redirect before the route renders, never inside the component
+- Treat the URL as the source of truth for filters, search, pagination, and tab state
+
+## Why Router + Query
+
+TanStack Router and TanStack Query together change how data fetching is structured:
+
+- **Loader prefetches data** before the component mounts
+- **Component reads from cache** via `useSuspenseQuery` — synchronously returns cached data
+- **No loading state on navigation** — the data is already there when the component renders
+- **Single source of truth** — the query cache serves both loaders and components
+
+The pattern flips the usual "fetch inside the component" model.
+
+## Route Definition
+
+### Code-Based Routes
+
+Define routes as a tree of `createRoute` calls. Best for full type inference and explicit composition.
+
+```ts
+import { createRootRoute, createRoute, createRouter } from "@tanstack/react-router";
+
+const rootRoute = createRootRoute({ component: RootLayout });
+
+const invoicesRoute = createRoute({
+  getParentRoute: () => rootRoute,
+  path: "/invoices",
+  component: InvoicesPage,
+});
+
+const invoiceDetailRoute = createRoute({
+  getParentRoute: () => invoicesRoute,
+  path: "$invoiceId",
+  component: InvoiceDetailPage,
+});
+
+const routeTree = rootRoute.addChildren([invoicesRoute, invoiceDetailRoute]);
+
+export const router = createRouter({ routeTree });
+
+declare module "@tanstack/react-router" {
+  interface Register {
+    router: typeof router;
+  }
+}
+```
+
+### File-Based Routes
+
+For larger apps, file-based routing reduces ceremony. Routes live in `src/routes/` and the generator creates the route tree:
+
+```
+src/routes/
+  __root.tsx            ← root layout
+  index.tsx             ← /
+  invoices/
+    index.tsx           ← /invoices
+    $invoiceId.tsx      ← /invoices/:invoiceId
+    _layout.tsx         ← shared layout for /invoices/*
+```
+
+Use the `@tanstack/router-plugin/vite` plugin to regenerate the route tree on save.
+
+**When to choose which:** code-based for libraries, embedded apps, or small projects; file-based for production apps with many routes.
+
+## Typed Path Params
+
+Path params are inferred from the path string:
+
+```ts
+const invoiceDetailRoute = createRoute({
+  getParentRoute: () => invoicesRoute,
+  path: "$invoiceId",
+  component: InvoiceDetailPage,
+});
+
+function InvoiceDetailPage() {
+  const { invoiceId } = invoiceDetailRoute.useParams(); // string, fully typed
+  return <InvoiceDetail id={invoiceId} />;
+}
+```
+
+For runtime-validated params (e.g., must be a CUID), use `parseParams`:
+
+```ts
+parseParams: ({ invoiceId }) => ({ invoiceId: z.string().cuid().parse(invoiceId) }),
+```
+
+## Typed Search Params
+
+Search params are the canonical place for filters, search queries, pagination, and tab selection — anywhere the state should be shareable, bookmarkable, and survive a refresh.
+
+```ts
+const invoicesRoute = createRoute({
+  getParentRoute: () => rootRoute,
+  path: "/invoices",
+  validateSearch: z.object({
+    status: z.enum(["all", "open", "paid"]).default("all"),
+    page: z.number().int().positive().default(1),
+    sort: z.enum(["dueDate", "amount"]).default("dueDate"),
+  }),
+  component: InvoicesPage,
+});
+
+function InvoicesPage() {
+  const { status, page, sort } = invoicesRoute.useSearch();
+  const navigate = invoicesRoute.useNavigate();
+
+  function setStatus(status: InvoiceStatus) {
+    navigate({ search: (prev) => ({ ...prev, status, page: 1 }) });
+  }
+
+  return <InvoiceTable status={status} page={page} sort={sort} onStatusChange={setStatus} />;
+}
+```
+
+Search params are validated on every navigation. Invalid values are coerced or rejected by the schema.
+
+## Loaders + TanStack Query (The Core Pattern)
+
+The recommended pattern: loaders prefetch with `queryClient.ensureQueryData`, components consume with `useSuspenseQuery`.
+
+```ts
+// 1. Define the query options outside the route so loader + component share them
+function invoicesQueryOptions(filters: InvoicesSearch) {
+  return queryOptions({
+    queryKey: ["invoices", filters],
+    queryFn: () => fetchInvoices(filters),
+    staleTime: 30_000,
+  });
+}
+
+// 2. The loader prefetches into the query cache
+const invoicesRoute = createRoute({
+  getParentRoute: () => rootRoute,
+  path: "/invoices",
+  validateSearch: invoicesSearchSchema,
+  loaderDeps: ({ search }) => search,
+  loader: ({ context, deps }) =>
+    context.queryClient.ensureQueryData(invoicesQueryOptions(deps)),
+  component: InvoicesPage,
+});
+
+// 3. The component reads from the cache — synchronous, no loading state
+function InvoicesPage() {
+  const search = invoicesRoute.useSearch();
+  const { data: invoices } = useSuspenseQuery(invoicesQueryOptions(search));
+  return <InvoiceTable invoices={invoices} />;
+}
+```
+
+What this gives you:
+- **No loading flicker on navigation** — data is in cache before render
+- **Stale-while-revalidate** — TanStack Query refetches in the background if stale
+- **Cache reuse** — going back to the page hits the cache instantly
+- **Prefetching** — `<Link preload="intent">` prefetches on hover
+
+### Router Setup with QueryClient in Context
+
+Pass the `queryClient` to the router so loaders can use it:
+
+```tsx
+const queryClient = new QueryClient({ /* ... */ });
+
+const router = createRouter({
+  routeTree,
+  context: { queryClient },
+  defaultPreload: "intent",
+});
+
+export function App() {
+  return (
+    <QueryClientProvider client={queryClient}>
+      <RouterProvider router={router} />
+    </QueryClientProvider>
+  );
+}
+```
+
+## Pending and Error Components
+
+Route-level components handle the boundary between routes. Different from in-page widgets.
+
+```ts
+const invoicesRoute = createRoute({
+  getParentRoute: () => rootRoute,
+  path: "/invoices",
+  loader: /* ... */,
+  pendingComponent: InvoicesPending,
+  errorComponent: InvoicesError,
+  component: InvoicesPage,
+});
+
+function InvoicesPending() {
+  return <TableSkeleton />;
+}
+
+function InvoicesError({ error }: { error: Error }) {
+  return (
+    <div role="alert">
+      <p>We couldn't load invoices.</p>
+      <p><small>{error.message}</small></p>
+    </div>
+  );
+}
+```
+
+**Use route-level `pendingComponent` / `errorComponent`** for the entire route transition (loader runs, then renders).
+**Use component-level `<Suspense>` / `<ErrorBoundary>`** for independent widgets within the page that can fail or load separately (see [`../react/error-boundaries.md`](../react/error-boundaries.md)).
+
+## Auth Guards with `beforeLoad`
+
+`beforeLoad` runs before the loader. It is the right place for authentication and authorization:
+
+```ts
+const dashboardRoute = createRoute({
+  getParentRoute: () => rootRoute,
+  path: "/dashboard",
+  beforeLoad: ({ context, location }) => {
+    if (!context.auth.isAuthenticated) {
+      throw redirect({
+        to: "/login",
+        search: { returnTo: location.href },
+      });
+    }
+  },
+  loader: /* ... */,
+  component: DashboardPage,
+});
+```
+
+`throw redirect(...)` short-circuits the route — the component never renders.
+
+Pass `auth` through the router context (same pattern as `queryClient`).
+
+## Code Splitting
+
+Lazy-load route components to reduce initial bundle size:
+
+```ts
+const invoicesRoute = createRoute({
+  getParentRoute: () => rootRoute,
+  path: "/invoices",
+  component: lazyRouteComponent(() => import("./InvoicesPage")),
+});
+```
+
+For file-based routes, prefix the file with `_` to make it lazy:
+
+```
+src/routes/invoices.lazy.tsx   ← lazy-loaded
+```
+
+## Route Context
+
+Share data down the route tree without prop drilling:
+
+```ts
+const router = createRouter({
+  routeTree,
+  context: {
+    queryClient,
+    auth: undefined!, // filled in by the auth route
+  },
+});
+
+const authRoute = createRoute({
+  getParentRoute: () => rootRoute,
+  beforeLoad: ({ context }) => ({
+    auth: { user: getCurrentUser(), isAuthenticated: !!getCurrentUser() },
+  }),
+});
+```
+
+Child routes inherit and can extend the context.
+
+## Type-Safe Navigation
+
+`Link`, `navigate`, and `redirect` are all typed against the route tree:
+
+```tsx
+import { Link } from "@tanstack/react-router";
+
+// Path and params are fully typed — typos and missing params are compile errors
+<Link to="/invoices/$invoiceId" params={{ invoiceId: invoice.id }}>
+  View invoice
+</Link>
+
+// Search params are typed against the route's validateSearch schema
+<Link
+  to="/invoices"
+  search={{ status: "open", page: 1 }}
+>
+  Open invoices
+</Link>
+
+// Preload on hover / focus
+<Link to="/invoices/$invoiceId" params={{ invoiceId }} preload="intent">
+  View
+</Link>
+```
+
+Programmatic navigation:
+
+```ts
+const navigate = useNavigate();
+navigate({ to: "/invoices/$invoiceId", params: { invoiceId } });
+```
+
+## Invalidation After Mutations
+
+When a mutation changes data, invalidate the relevant queries and optionally navigate:
+
+```tsx
+const { mutate } = useMutation({
+  mutationFn: createInvoice,
+  onSuccess: async (newInvoice) => {
+    await queryClient.invalidateQueries({ queryKey: ["invoices"] });
+    navigate({ to: "/invoices/$invoiceId", params: { invoiceId: newInvoice.id } });
+  },
+});
+```
+
+For server-driven navigation (e.g., after delete, go back to the list):
+
+```ts
+onSuccess: () => {
+  queryClient.invalidateQueries({ queryKey: ["invoices"] });
+  navigate({ to: "/invoices", search: { status: "all", page: 1 } });
+};
+```
+
+## DO NOT
+
+- Define routes with stringly-typed paths — use `createRoute` or file-based routing for type inference
+- Fetch data inside the component on mount — use the loader
+- Use `useEffect` to read URL params — use `useSearch` / `useParams`
+- Put search-param logic in component state and sync it to the URL — use the router's `validateSearch`
+- Skip `validateSearch` "just for now" — invalid params will leak into your queries and cause cache pollution
+- Build custom auth-redirect logic inside components — use `beforeLoad`
+
+## PRIORITY
+
+```
+Loader-prefetched + Suspense queries > Component-level fetching
+Typed search params > Component state for shareable values
+beforeLoad redirects > Component-level redirects
+Route errorComponent > Component-level ErrorBoundary (for route-scoped errors)
+```
+
+## See Also
+
+- [`tanstack-query.md`](tanstack-query.md) — query options, mutations, invalidation
+- [`../react/state-management.md`](../react/state-management.md) — URL state at the top of the hierarchy
+- [`../react/error-boundaries.md`](../react/error-boundaries.md) — component-level error and loading boundaries
+- [`../architecture/api-design.md`](../architecture/api-design.md) — API client and pagination patterns

package/templates/standards/tooling/tanstack.md

@@ -0,0 +1,31 @@
+# TanStack
+
+The TanStack family is the preferred toolkit for routing, server state, and forms.
+
+| Library | Doc | Purpose |
+|---|---|---|
+| TanStack Router | [`tanstack-router.md`](tanstack-router.md) | Type-safe routing, loaders, typed search params |
+| TanStack Query | [`tanstack-query.md`](tanstack-query.md) | Server state, caching, mutations |
+| TanStack Form | [`../react/forms.md`](../react/forms.md) | Type-safe form state with schema validation |
+
+## Why TanStack
+
+- Each library is independent but composes cleanly with the others
+- Type inference flows end-to-end — fewer hand-typed DTOs
+- Schema validation (Zod) provides a consistent backbone across router, query, and form
+- Router + Query together eliminate loading flicker on navigation — see [`tanstack-router.md`](tanstack-router.md)
+
+## When All Three Compose
+
+A typical data flow uses all three:
+
+1. **Router** loads data in a `loader` via `queryClient.ensureQueryData`
+2. **Query** caches it; components consume it via `useSuspenseQuery`
+3. **Form** mutations call `queryClient.invalidateQueries` after submission
+4. The Router navigates to the next route, which may already be prefetched
+
+## See Also
+
+- [`../react/state-management.md`](../react/state-management.md) — state hierarchy (URL > server > local > context)
+- [`../react/forms.md`](../react/forms.md) — TanStack Form patterns
+- [`../architecture/api-design.md`](../architecture/api-design.md) — API contracts that feed these libraries

package/templates/standards/tooling/vite.md

@@ -0,0 +1,135 @@
+# Vite
+
+## Purpose
+
+Vite is the preferred build tool for React applications and libraries. It provides fast dev-server HMR and optimized production builds.
+
+## Recommended Config
+
+```ts
+// vite.config.ts
+import { defineConfig } from "vite";
+import react from "@vitejs/plugin-react";
+import tsconfigPaths from "vite-tsconfig-paths";
+
+export default defineConfig({
+  plugins: [
+    react(),
+    tsconfigPaths(), // resolves ~/... aliases from tsconfig paths
+  ],
+  build: {
+    target: "es2022",
+    sourcemap: true,
+  },
+  server: {
+    port: 3000,
+  },
+});
+```
+
+## Path Aliases
+
+Use `~/` for absolute imports. Configure in `tsconfig.json` and resolve with `vite-tsconfig-paths`:
+
+```json
+// tsconfig.json
+{
+  "compilerOptions": {
+    "paths": {
+      "~/*": ["./src/*"]
+    }
+  }
+}
+```
+
+```ts
+// Usage
+import { InvoiceTable } from "~/features/invoices/InvoiceTable";
+import { formatCurrency } from "~/shared/utils/format-currency";
+```
+
+## Environment Variables
+
+Vite exposes env vars prefixed with `VITE_` to the client:
+
+```
+VITE_API_BASE_URL=https://api.example.com
+```
+
+```ts
+// Access in code
+const apiBase = import.meta.env.VITE_API_BASE_URL;
+```
+
+Validate env vars at startup:
+
+```ts
+// src/lib/env.ts
+import { z } from "zod";
+
+const envSchema = z.object({
+  VITE_API_BASE_URL: z.string().url(),
+});
+
+export const env = envSchema.parse(import.meta.env);
+```
+
+## Vitest Integration
+
+Vitest runs inside Vite — same config, same transforms:
+
+```ts
+// vite.config.ts
+import { defineConfig } from "vite";
+
+export default defineConfig({
+  plugins: [react(), tsconfigPaths()],
+  test: {
+    environment: "jsdom",
+    setupFiles: ["./src/test/setup.ts"],
+    globals: true,
+  },
+});
+```
+
+```ts
+// src/test/setup.ts
+import "@testing-library/jest-dom";
+```
+
+## Code Splitting
+
+Vite splits by dynamic import automatically:
+
+```ts
+const InvoicePage = lazy(() => import("~/features/invoices/InvoicePage"));
+```
+
+For manual chunk control:
+
+```ts
+// vite.config.ts
+build: {
+  rollupOptions: {
+    output: {
+      manualChunks: {
+        vendor: ["react", "react-dom"],
+        tanstack: ["@tanstack/react-query", "@tanstack/react-router"],
+      },
+    },
+  },
+},
+```
+
+## DO NOT
+
+- Use `process.env` in Vite client code — use `import.meta.env`
+- Commit `.env` files with secrets — use `.env.local` (gitignored)
+- Disable sourcemaps in production without good reason
+
+## See Also
+
+- [`biome.md`](biome.md) — lint and format
+- [`dependencies.md`](dependencies.md) — bundle impact tools
+- [`../security/secrets.md`](../security/secrets.md) — env var validation
+- [`../react/testing.md`](../react/testing.md) — Vitest runs inside Vite

package/templates/standards/typescript/anti-patterns.md

@@ -0,0 +1,107 @@
+# TypeScript Anti-Patterns
+
+## `any`
+
+```ts
+// BAD — erases all type safety
+function process(data: any) {
+  return data.value;
+}
+
+// GOOD — use unknown and narrow
+function process(data: unknown) {
+  if (typeof data === "object" && data !== null && "value" in data) {
+    return data.value;
+  }
+  throw new Error("Unexpected data shape");
+}
+```
+
+## Type Assertions
+
+```ts
+// BAD — silences the compiler without verification
+const user = JSON.parse(raw) as User;
+
+// GOOD — validate before using
+const user = userSchema.parse(JSON.parse(raw));
+```
+
+## Enums
+
+```ts
+// BAD — compiled JS artifact, not tree-shakeable, verbose
+enum Status {
+  Active = "ACTIVE",
+  Inactive = "INACTIVE",
+}
+
+// GOOD — plain union, zero runtime cost
+type Status = "ACTIVE" | "INACTIVE";
+```
+
+## DTO Duplication
+
+```ts
+// BAD — same shape defined twice
+// api/users.ts
+interface ApiUser { id: string; name: string; }
+
+// frontend/types.ts
+interface FrontendUser { id: string; name: string; }
+
+// GOOD — single schema, inferred types
+const userSchema = z.object({ id: z.string(), name: z.string() });
+type User = z.infer<typeof userSchema>;
+```
+
+## Type Gymnastics
+
+```ts
+// BAD — deeply conditional mapped types that take 10 minutes to understand
+type DeepPartialReadonly<T> =
+  T extends object
+    ? { readonly [K in keyof T]?: DeepPartialReadonly<T[K]> }
+    : T;
+
+// If you need this, ask whether the data model is the real problem
+```
+
+## `@ts-ignore` Without Explanation
+
+```ts
+// BAD
+// @ts-ignore
+doSomethingWeird(value);
+
+// ACCEPTABLE — only when necessary, always with context
+// @ts-expect-error — third-party type definition is wrong, see github.com/foo/bar/issues/123
+doSomethingWeird(value);
+```
+
+## Non-null Assertions Without Verification
+
+```ts
+// BAD — crashes at runtime if undefined
+const name = user!.profile!.name;
+
+// GOOD
+const name = user?.profile?.name ?? "Anonymous";
+```
+
+## `object` or `{}` as a Type
+
+```ts
+// BAD — accepts almost anything
+function format(value: object): string { ... }
+function format(value: {}): string { ... }
+
+// GOOD — be explicit
+function format(value: Record<string, string>): string { ... }
+```
+
+## See Also
+
+- [`rules.md`](rules.md) — the positive rules these anti-patterns violate
+- [`validation.md`](validation.md) — runtime validation for `unknown` data
+- [`error-handling.md`](error-handling.md) — async, throwing, and preserving error context