devstack 0.1.0

package/vendor/skills/skills/tanstack-router-best-practices/SKILL.md

@@ -0,0 +1,114 @@
+---
+name: tanstack-router-best-practices
+description: TanStack Router best practices for type-safe routing, data loading, search params, and navigation. Activate when building React applications with complex routing needs.
+---
+
+# TanStack Router Best Practices
+
+Comprehensive guidelines for implementing TanStack Router patterns in React applications. These rules optimize type safety, data loading, navigation, and code organization.
+
+## When to Apply
+
+- Setting up application routing
+- Creating new routes and layouts
+- Implementing search parameter handling
+- Configuring data loaders
+- Setting up code splitting
+- Integrating with TanStack Query
+- Refactoring navigation patterns
+
+## Rule Categories by Priority
+
+| Priority | Category           | Rules   | Impact                                          |
+| -------- | ------------------ | ------- | ----------------------------------------------- |
+| CRITICAL | Type Safety        | 4 rules | Prevents runtime errors and enables refactoring |
+| CRITICAL | Route Organization | 5 rules | Ensures maintainable route structure            |
+| HIGH     | Router Config      | 1 rule  | Global router defaults                          |
+| HIGH     | Data Loading       | 6 rules | Optimizes data fetching and caching             |
+| HIGH     | Search Params      | 5 rules | Enables type-safe URL state                     |
+| HIGH     | Error Handling     | 1 rule  | Handles 404 and errors gracefully               |
+| MEDIUM   | Navigation         | 5 rules | Improves UX and accessibility                   |
+| MEDIUM   | Code Splitting     | 3 rules | Reduces bundle size                             |
+| MEDIUM   | Preloading         | 3 rules | Improves perceived performance                  |
+| LOW      | Route Context      | 3 rules | Enables dependency injection                    |
+
+## Quick Reference
+
+### Type Safety (Prefix: `ts-`)
+
+- `ts-register-router` — Register router type for global inference
+- `ts-use-from-param` — Use `from` parameter for type narrowing
+- `ts-route-context-typing` — Type route context with createRootRouteWithContext
+- `ts-query-options-loader` — Use queryOptions in loaders for type inference
+
+### Router Config (Prefix: `router-`)
+
+- `router-default-options` — Configure router defaults (scrollRestoration, defaultErrorComponent, etc.)
+
+### Route Organization (Prefix: `org-`)
+
+- `org-file-based-routing` — Prefer file-based routing for conventions
+- `org-route-tree-structure` — Follow hierarchical route tree patterns
+- `org-pathless-layouts` — Use pathless routes for shared layouts
+- `org-index-routes` — Understand index vs layout routes
+- `org-virtual-routes` — Understand virtual file routes
+
+### Data Loading (Prefix: `load-`)
+
+- `load-use-loaders` — Use route loaders for data fetching
+- `load-loader-deps` — Define loaderDeps for cache control
+- `load-ensure-query-data` — Use ensureQueryData with TanStack Query
+- `load-deferred-data` — Split critical and non-critical data
+- `load-error-handling` — Handle loader errors appropriately
+- `load-parallel` — Leverage parallel route loading
+
+### Search Params (Prefix: `search-`)
+
+- `search-validation` — Always validate search params
+- `search-type-inheritance` — Leverage parent search param types
+- `search-middleware` — Use search param middleware
+- `search-defaults` — Provide sensible defaults
+- `search-custom-serializer` — Configure custom search param serializers
+
+### Error Handling (Prefix: `err-`)
+
+- `err-not-found` — Handle not-found routes properly
+
+### Navigation (Prefix: `nav-`)
+
+- `nav-link-component` — Prefer Link component for navigation
+- `nav-active-states` — Configure active link states
+- `nav-use-navigate` — Use useNavigate for programmatic navigation
+- `nav-relative-paths` — Understand relative path navigation
+- `nav-route-masks` — Use route masks for modal URLs
+
+### Code Splitting (Prefix: `split-`)
+
+- `split-lazy-routes` — Use .lazy.tsx for code splitting
+- `split-critical-path` — Keep critical config in main route file
+- `split-auto-splitting` — Enable autoCodeSplitting when possible
+
+### Preloading (Prefix: `preload-`)
+
+- `preload-intent` — Enable intent-based preloading
+- `preload-stale-time` — Configure preload stale time
+- `preload-manual` — Use manual preloading strategically
+
+### Route Context (Prefix: `ctx-`)
+
+- `ctx-root-context` — Define context at root route
+- `ctx-before-load` — Extend context in beforeLoad
+- `ctx-dependency-injection` — Use context for dependency injection
+
+## How to Use
+
+Each rule file in the `rules/` directory contains:
+
+1. **Explanation** — Why this pattern matters
+2. **Bad Example** — Anti-pattern to avoid
+3. **Good Example** — Recommended implementation
+4. **Context** — When to apply or skip this rule
+
+## Full Reference
+
+See individual rule files in `rules/` directory for detailed guidance and code examples.

package/vendor/skills/skills/tanstack-router-best-practices/rules/ctx-root-context.md

@@ -0,0 +1,170 @@
+# ctx-root-context: Define Context at Root Route
+
+## Priority: LOW
+
+## Explanation
+
+Use `createRootRouteWithContext` to define typed context that flows through your entire route tree. This enables dependency injection for things like query clients, auth state, and services.
+
+## Bad Example
+
+```tsx
+// No context - importing globals directly
+// routes/__root.tsx
+import { createRootRoute } from "@tanstack/react-router";
+import { queryClient } from "@/lib/query-client"; // Global import
+
+export const Route = createRootRoute({
+  component: RootComponent,
+});
+
+// routes/posts.tsx
+import { queryClient } from "@/lib/query-client"; // Import again
+
+export const Route = createFileRoute("/posts")({
+  loader: async () => {
+    // Using global - harder to test, couples to implementation
+    return queryClient.ensureQueryData(postQueries.list());
+  },
+});
+```
+
+## Good Example
+
+```tsx
+// routes/__root.tsx
+import { createRootRouteWithContext, Outlet } from "@tanstack/react-router";
+import { QueryClient } from "@tanstack/react-query";
+
+// Define the context interface
+interface RouterContext {
+  queryClient: QueryClient;
+  auth: {
+    user: User | null;
+    isAuthenticated: boolean;
+  };
+}
+
+export const Route = createRootRouteWithContext<RouterContext>()({
+  component: RootComponent,
+});
+
+function RootComponent() {
+  return (
+    <>
+      <Header />
+      <main>
+        <Outlet />
+      </main>
+      <Footer />
+    </>
+  );
+}
+
+// router.tsx - Provide context when creating router
+import { createRouter } from "@tanstack/react-router";
+import { QueryClient } from "@tanstack/react-query";
+import { setupRouterSsrQueryIntegration } from "@tanstack/react-router-ssr-query";
+import { routeTree } from "./routeTree.gen";
+
+export function getRouter(auth: RouterContext["auth"] = { user: null, isAuthenticated: false }) {
+  const queryClient = new QueryClient();
+
+  const router = createRouter({
+    routeTree,
+    context: {
+      queryClient,
+      auth,
+    },
+    defaultPreload: "intent",
+    defaultPreloadStaleTime: 0,
+    scrollRestoration: true,
+  });
+
+  setupRouterSsrQueryIntegration({ router, queryClient });
+
+  return router;
+}
+
+// routes/posts.tsx - Use context in loaders
+export const Route = createFileRoute("/posts")({
+  loader: async ({ context: { queryClient } }) => {
+    // Context is typed and injected
+    return queryClient.ensureQueryData(postQueries.list());
+  },
+});
+```
+
+## Good Example: Auth-Protected Routes
+
+```tsx
+// routes/__root.tsx
+interface RouterContext {
+  queryClient: QueryClient;
+  auth: AuthState;
+}
+
+export const Route = createRootRouteWithContext<RouterContext>()({
+  component: RootComponent,
+});
+
+// routes/_authenticated.tsx - Layout route for protected pages
+export const Route = createFileRoute("/_authenticated")({
+  beforeLoad: async ({ context, location }) => {
+    if (!context.auth.isAuthenticated) {
+      throw redirect({
+        to: "/login",
+        search: { redirect: location.href },
+      });
+    }
+  },
+  component: AuthenticatedLayout,
+});
+
+// routes/_authenticated/dashboard.tsx
+export const Route = createFileRoute("/_authenticated/dashboard")({
+  loader: async ({ context: { queryClient, auth } }) => {
+    // We know user is authenticated from parent beforeLoad
+    return queryClient.ensureQueryData(dashboardQueries.forUser(auth.user!.id));
+  },
+});
+```
+
+## Extending Context with beforeLoad
+
+```tsx
+// routes/posts/$postId.tsx
+export const Route = createFileRoute("/posts/$postId")({
+  beforeLoad: async ({ context, params }) => {
+    // Extend context with route-specific data
+    const post = await fetchPost(params.postId);
+
+    return {
+      post, // Available to this route and children
+    };
+  },
+  loader: async ({ context }) => {
+    // context now includes 'post' from beforeLoad
+    const comments = await fetchComments(context.post.id);
+    return { comments };
+  },
+});
+```
+
+## Context vs. Loader Data
+
+| Context                                        | Loader Data                  |
+| ---------------------------------------------- | ---------------------------- |
+| Available in beforeLoad, loader, and component | Only available in component  |
+| Set at router creation or in beforeLoad        | Returned from loader         |
+| Good for services, clients, auth               | Good for route-specific data |
+| Flows down to all children                     | Specific to route            |
+
+## Context
+
+- Type the context interface in `createRootRouteWithContext<T>()`
+- Provide context when calling `createRouter({ context: {...} })`
+- Context flows from root to all nested routes
+- Use `beforeLoad` to extend context for specific subtrees
+- Enables testability - inject mocks in tests
+- Avoids global imports and singletons

package/vendor/skills/skills/tanstack-router-best-practices/rules/err-not-found.md

@@ -0,0 +1,194 @@
+# err-not-found: Handle Not-Found Routes Properly
+
+## Priority: HIGH
+
+## Explanation
+
+Configure `notFoundComponent` to handle 404 errors gracefully. TanStack Router provides not-found handling at multiple levels: root, route-specific, and programmatic via `notFound()`. Proper configuration prevents blank screens and improves UX.
+
+## Bad Example
+
+```tsx
+// No not-found handling - shows blank screen or error
+const router = createRouter({
+  routeTree,
+  // Missing defaultNotFoundComponent
+});
+
+// Or throwing generic error
+export const Route = createFileRoute("/posts/$postId")({
+  loader: async ({ params }) => {
+    const post = await fetchPost(params.postId);
+    if (!post) {
+      throw new Error("Not found"); // Generic error, not proper 404
+    }
+    return post;
+  },
+});
+```
+
+## Good Example: Root-Level Not Found
+
+```tsx
+// routes/__root.tsx
+export const Route = createRootRoute({
+  component: RootComponent,
+  notFoundComponent: GlobalNotFound,
+});
+
+function GlobalNotFound() {
+  return (
+    <div className="not-found">
+      <h1>404 - Page Not Found</h1>
+      <p>The page you're looking for doesn't exist.</p>
+      <Link to="/">Go Home</Link>
+    </div>
+  );
+}
+
+// router.tsx - Can also set default
+const router = createRouter({
+  routeTree,
+  defaultNotFoundComponent: () => (
+    <div>
+      <h1>404</h1>
+      <Link to="/">Return Home</Link>
+    </div>
+  ),
+});
+```
+
+## Good Example: Route-Specific Not Found
+
+```tsx
+// routes/posts/$postId.tsx
+import { createFileRoute, notFound } from "@tanstack/react-router";
+
+export const Route = createFileRoute("/posts/$postId")({
+  loader: async ({ params }) => {
+    const post = await fetchPost(params.postId);
+    if (!post) {
+      throw notFound(); // Proper 404 handling
+    }
+    return post;
+  },
+  notFoundComponent: PostNotFound, // Custom 404 for this route
+  component: PostPage,
+});
+
+function PostNotFound() {
+  const { postId } = Route.useParams();
+
+  return (
+    <div>
+      <h1>Post Not Found</h1>
+      <p>No post exists with ID: {postId}</p>
+      <Link to="/posts">Browse all posts</Link>
+    </div>
+  );
+}
+```
+
+## Good Example: Not Found with Data
+
+```tsx
+export const Route = createFileRoute("/users/$username")({
+  loader: async ({ params }) => {
+    const user = await fetchUser(params.username);
+    if (!user) {
+      throw notFound({
+        // Pass data to notFoundComponent
+        data: {
+          username: params.username,
+          suggestions: await fetchSimilarUsernames(params.username),
+        },
+      });
+    }
+    return user;
+  },
+  notFoundComponent: UserNotFound,
+});
+
+function UserNotFound() {
+  const { data } = Route.useMatch();
+
+  return (
+    <div>
+      <h1>User @{data?.username} not found</h1>
+      {data?.suggestions?.length > 0 && (
+        <div>
+          <p>Did you mean:</p>
+          <ul>
+            {data.suggestions.map(username => (
+              <li key={username}>
+                <Link to="/users/$username" params={{ username }}>
+                  @{username}
+                </Link>
+              </li>
+            ))}
+          </ul>
+        </div>
+      )}
+    </div>
+  );
+}
+```
+
+## Good Example: Catch-All Route
+
+```tsx
+// routes/$.tsx - Catch-all splat route
+export const Route = createFileRoute("/$")({
+  component: CatchAllNotFound,
+});
+
+function CatchAllNotFound() {
+  const { _splat } = Route.useParams();
+
+  return (
+    <div>
+      <h1>Page Not Found</h1>
+      <p>No page exists at: /{_splat}</p>
+      <Link to="/">Go to homepage</Link>
+    </div>
+  );
+}
+```
+
+## Good Example: Nested Not Found Bubbling
+
+```tsx
+// Not found bubbles up through route tree
+// routes/posts.tsx
+export const Route = createFileRoute("/posts")({
+  notFoundComponent: PostsNotFound, // Catches child 404s too
+});
+
+// routes/posts/$postId.tsx
+export const Route = createFileRoute("/posts/$postId")({
+  loader: async ({ params }) => {
+    const post = await fetchPost(params.postId);
+    if (!post) throw notFound();
+    return post;
+  },
+  // No notFoundComponent - bubbles to parent
+});
+
+// routes/posts/$postId/comments.tsx
+export const Route = createFileRoute("/posts/$postId/comments")({
+  loader: async ({ params }) => {
+    const comments = await fetchComments(params.postId);
+    if (!comments) throw notFound(); // Bubbles to /posts notFoundComponent
+    return comments;
+  },
+});
+```
+
+## Context
+
+- `notFound()` throws a special error caught by nearest `notFoundComponent`
+- Not found bubbles up the route tree if not handled locally
+- Use `defaultNotFoundComponent` on router for global fallback
+- Pass data to `notFound({ data })` for contextual 404 pages
+- Catch-all routes (`/$`) can handle truly unknown paths
+- Different from error boundaries - specifically for 404 cases

package/vendor/skills/skills/tanstack-router-best-practices/rules/load-ensure-query-data.md

@@ -0,0 +1,147 @@
+# load-ensure-query-data: Use ensureQueryData with TanStack Query
+
+## Priority: HIGH
+
+## Explanation
+
+When integrating TanStack Router with TanStack Query, use `queryClient.ensureQueryData()` in loaders instead of `prefetchQuery()`. This respects the cache, awaits data if missing, and returns the data for potential use.
+
+## Bad Example
+
+```tsx
+// Using prefetchQuery - doesn't return data, can't await stale check
+export const Route = createFileRoute("/posts/$postId")({
+  loader: async ({ params, context: { queryClient } }) => {
+    // prefetchQuery never throws, swallows errors
+    queryClient.prefetchQuery({
+      queryKey: ["posts", params.postId],
+      queryFn: () => fetchPost(params.postId),
+    });
+    // No await - might not complete before render
+    // No return value to use
+  },
+});
+
+// Fetching directly - bypasses TanStack Query cache
+export const Route = createFileRoute("/posts")({
+  loader: async () => {
+    const posts = await fetchPosts(); // Not cached
+    return { posts };
+  },
+});
+```
+
+## Good Example
+
+```tsx
+// Define queryOptions for reuse
+const postQueryOptions = (postId: string) =>
+  queryOptions({
+    queryKey: ["posts", postId],
+    queryFn: () => fetchPost(postId),
+    staleTime: 5 * 60 * 1000, // 5 minutes
+  });
+
+export const Route = createFileRoute("/posts/$postId")({
+  loader: async ({ params, context: { queryClient } }) => {
+    // ensureQueryData:
+    // - Returns cached data if fresh
+    // - Fetches and caches if missing or stale
+    // - Awaits completion
+    // - Throws on error (caught by error boundary)
+    await queryClient.ensureQueryData(postQueryOptions(params.postId));
+  },
+  component: PostPage,
+});
+
+function PostPage() {
+  const { postId } = Route.useParams();
+
+  // Data guaranteed to exist from loader
+  const { data: post } = useSuspenseQuery(postQueryOptions(postId));
+
+  return <PostContent post={post} />;
+}
+```
+
+## Good Example: Multiple Parallel Queries
+
+```tsx
+export const Route = createFileRoute("/dashboard")({
+  loader: async ({ context: { queryClient } }) => {
+    // Parallel data fetching
+    await Promise.all([
+      queryClient.ensureQueryData(statsQueries.overview()),
+      queryClient.ensureQueryData(activityQueries.recent()),
+      queryClient.ensureQueryData(notificationQueries.unread()),
+    ]);
+  },
+});
+```
+
+## Good Example: Dependent Queries
+
+```tsx
+export const Route = createFileRoute("/users/$userId/posts")({
+  loader: async ({ params, context: { queryClient } }) => {
+    // First query needed for second
+    const user = await queryClient.ensureQueryData(userQueries.detail(params.userId));
+
+    // Dependent query uses result
+    await queryClient.ensureQueryData(postQueries.byAuthor(user.id));
+  },
+});
+```
+
+## Router Configuration for TanStack Query
+
+```tsx
+// router.tsx
+const queryClient = new QueryClient({
+  defaultOptions: {
+    queries: {
+      staleTime: 60 * 1000, // 1 minute default
+    },
+  },
+});
+
+export const router = createRouter({
+  routeTree,
+  context: { queryClient },
+
+  // Let TanStack Query manage caching
+  defaultPreloadStaleTime: 0,
+
+  // SSR: Dehydrate query cache
+  dehydrate: () => ({
+    queryClientState: dehydrate(queryClient),
+  }),
+
+  // SSR: Hydrate on client
+  hydrate: dehydrated => {
+    hydrate(queryClient, dehydrated.queryClientState);
+  },
+
+  // Wrap with QueryClientProvider
+  Wrap: ({ children }) => (
+    <QueryClientProvider client={queryClient}>{children}</QueryClientProvider>
+  ),
+});
+```
+
+## ensureQueryData vs prefetchQuery vs fetchQuery
+
+| Method            | Returns | Throws | Awaits | Use Case                       |
+| ----------------- | ------- | ------ | ------ | ------------------------------ |
+| `ensureQueryData` | Data    | Yes    | Yes    | Route loaders (recommended)    |
+| `prefetchQuery`   | void    | No     | Yes    | Background prefetching         |
+| `fetchQuery`      | Data    | Yes    | Yes    | When you need data immediately |
+
+## Context
+
+- `ensureQueryData` is the recommended method for route loaders
+- Respects `staleTime` - won't refetch fresh cached data
+- Errors propagate to route error boundaries
+- Use `queryOptions()` factory for type-safe, reusable query definitions
+- Set `defaultPreloadStaleTime: 0` to let TanStack Query manage cache
+- Pair with `useSuspenseQuery` in components for guaranteed data