devstack 0.1.0

package/vendor/skills/skills/tanstack-router-best-practices/rules/org-virtual-routes.md

@@ -0,0 +1,133 @@
+# org-virtual-routes: Understand Virtual File Routes
+
+## Priority: LOW
+
+## Explanation
+
+Virtual routes are automatically generated placeholder routes in the route tree when you have a `.lazy.tsx` file without a corresponding main route file. They provide the minimal configuration needed to anchor lazy-loaded components.
+
+## Bad Example
+
+```tsx
+// Creating unnecessary boilerplate main route files
+// routes/settings.tsx - Just to have a file
+export const Route = createFileRoute("/settings")({
+  // Empty - no loader, no beforeLoad, nothing
+});
+
+// routes/settings.lazy.tsx - Actual component
+export const Route = createLazyFileRoute("/settings")({
+  component: SettingsPage,
+});
+
+// The main file is unnecessary boilerplate
+```
+
+## Good Example: Let Virtual Routes Handle It
+
+```tsx
+// Delete routes/settings.tsx entirely!
+
+// routes/settings.lazy.tsx - Only file needed
+export const Route = createLazyFileRoute("/settings")({
+  component: SettingsPage,
+  pendingComponent: SettingsLoading,
+  errorComponent: SettingsError,
+});
+
+function SettingsPage() {
+  return <div>Settings Content</div>;
+}
+
+// TanStack Router auto-generates a virtual route:
+// {
+//   path: '/settings',
+//   // Minimal config to anchor the lazy file
+// }
+```
+
+## Good Example: When You DO Need Main Route File
+
+```tsx
+// routes/dashboard.tsx - Need this for loader/beforeLoad
+export const Route = createFileRoute("/dashboard")({
+  beforeLoad: async ({ context }) => {
+    if (!context.auth.isAuthenticated) {
+      throw redirect({ to: "/login" });
+    }
+  },
+  loader: async ({ context: { queryClient } }) => {
+    await queryClient.ensureQueryData(dashboardQueries.stats());
+  },
+  // Component is in lazy file
+});
+
+// routes/dashboard.lazy.tsx
+export const Route = createLazyFileRoute("/dashboard")({
+  component: DashboardPage,
+  pendingComponent: DashboardSkeleton,
+});
+
+// Main file IS needed here because we have loader/beforeLoad
+```
+
+## Decision Guide
+
+| Route Has...                         | Need Main File? | Use Virtual? |
+| ------------------------------------ | --------------- | ------------ |
+| Only component                       | No              | Yes          |
+| loader                               | Yes             | No           |
+| beforeLoad                           | Yes             | No           |
+| validateSearch                       | Yes             | No           |
+| loaderDeps                           | Yes             | No           |
+| Just pendingComponent/errorComponent | No              | Yes          |
+
+## Good Example: File Structure with Virtual Routes
+
+```
+routes/
+├── __root.tsx              # Always needed
+├── index.tsx               # Has loader
+├── about.lazy.tsx          # Virtual route (no main file)
+├── contact.lazy.tsx        # Virtual route (no main file)
+├── dashboard.tsx           # Has beforeLoad (auth)
+├── dashboard.lazy.tsx      # Component
+├── posts.tsx               # Has loader
+├── posts.lazy.tsx          # Component
+├── posts/
+│   ├── $postId.tsx         # Has loader
+│   └── $postId.lazy.tsx    # Component
+└── settings/
+    ├── index.lazy.tsx      # Virtual route
+    ├── profile.lazy.tsx    # Virtual route
+    └── security.tsx        # Has beforeLoad (requires re-auth)
+```
+
+## Good Example: Generated Route Tree
+
+```tsx
+// routeTree.gen.ts (auto-generated)
+import { Route as rootRoute } from './routes/__root'
+import { Route as aboutLazyRoute } from './routes/about.lazy'  // Virtual parent
+
+export const routeTree = rootRoute.addChildren([
+  // Virtual route created for about.lazy.tsx
+  createRoute({
+    path: '/about',
+    getParentRoute: () => rootRoute,
+  }).lazy(() => import('./routes/about.lazy').then(m => m.Route)),
+
+  // Regular route with explicit main file
+  dashboardRoute.addChildren([...]),
+])
+```
+
+## Context
+
+- Virtual routes reduce boilerplate for simple pages
+- Only works with file-based routing
+- Auto-generated in `routeTree.gen.ts`
+- Main route file needed for any "critical path" config
+- Critical: loader, beforeLoad, validateSearch, loaderDeps, context
+- Non-critical (can be in lazy): component, pendingComponent, errorComponent
+- Check generated route tree to verify virtual routes

package/vendor/skills/skills/tanstack-router-best-practices/rules/preload-intent.md

@@ -0,0 +1,133 @@
+# preload-intent: Enable Intent-Based Preloading
+
+## Priority: MEDIUM
+
+## Explanation
+
+Configure `defaultPreload: 'intent'` to preload routes when users hover or focus links. This loads data before the click, making navigation feel instant.
+
+## Bad Example
+
+```tsx
+// No preloading configured - data loads after click
+const router = createRouter({
+  routeTree,
+  // No defaultPreload - user waits after every navigation
+});
+
+// Each navigation shows loading state
+function PostList({ posts }: { posts: Post[] }) {
+  return (
+    <ul>
+      {posts.map(post => (
+        <li key={post.id}>
+          <Link to="/posts/$postId" params={{ postId: post.id }}>
+            {post.title}
+          </Link>
+          {/* Click → wait for data → render */}
+        </li>
+      ))}
+    </ul>
+  );
+}
+```
+
+## Good Example
+
+```tsx
+// router.tsx - Enable preloading by default
+const router = createRouter({
+  routeTree,
+  defaultPreload: "intent", // Preload on hover/focus
+  defaultPreloadDelay: 50, // Wait 50ms before starting
+});
+
+declare module "@tanstack/react-router" {
+  interface Register {
+    router: typeof router;
+  }
+}
+
+// Links automatically preload on hover
+function PostList({ posts }: { posts: Post[] }) {
+  return (
+    <ul>
+      {posts.map(post => (
+        <li key={post.id}>
+          <Link to="/posts/$postId" params={{ postId: post.id }}>
+            {post.title}
+          </Link>
+          {/* Hover → preload starts → click → instant navigation */}
+        </li>
+      ))}
+    </ul>
+  );
+}
+```
+
+## Preload Options
+
+```tsx
+// Router-level defaults
+const router = createRouter({
+  routeTree,
+  defaultPreload: 'intent',       // 'intent' | 'render' | 'viewport' | false
+  defaultPreloadDelay: 50,        // ms before preload starts
+  defaultPreloadStaleTime: 30000, // 30s - how long preloaded data stays fresh
+})
+
+// Link-level overrides
+<Link
+  to="/heavy-page"
+  preload={false}  // Disable for this specific link
+>
+  Heavy Page
+</Link>
+
+<Link
+  to="/critical-page"
+  preload="render"  // Preload immediately when Link renders
+>
+  Critical Page
+</Link>
+```
+
+## Preload Strategies
+
+| Strategy     | Behavior                          | Use Case                    |
+| ------------ | --------------------------------- | --------------------------- |
+| `'intent'`   | Preload on hover/focus            | Default for most links      |
+| `'render'`   | Preload when Link mounts          | Critical next pages         |
+| `'viewport'` | Preload when Link enters viewport | Below-fold content          |
+| `false`      | No preloading                     | Heavy, rarely-visited pages |
+
+## Good Example: With TanStack Query Integration
+
+```tsx
+// When using TanStack Query, disable router cache
+const router = createRouter({
+  routeTree,
+  defaultPreload: "intent",
+  defaultPreloadStaleTime: 0, // Let TanStack Query manage cache
+  context: {
+    queryClient,
+  },
+});
+
+// Route loader uses TanStack Query
+export const Route = createFileRoute("/posts/$postId")({
+  loader: async ({ params, context: { queryClient } }) => {
+    // ensureQueryData respects TanStack Query's staleTime
+    await queryClient.ensureQueryData(postQueries.detail(params.postId));
+  },
+});
+```
+
+## Context
+
+- Preloading loads route code AND executes loaders
+- `preloadDelay` prevents excessive requests on quick mouse movements
+- Preloaded data is garbage collected after `preloadStaleTime`
+- Works with both router caching and external caching (TanStack Query)
+- Mobile: Consider `'viewport'` since hover isn't available
+- Monitor network tab to verify preloading works correctly

package/vendor/skills/skills/tanstack-router-best-practices/rules/router-default-options.md

@@ -0,0 +1,159 @@
+# router-default-options: Configure Router Default Options
+
+## Priority: HIGH
+
+## Explanation
+
+TanStack Router's `createRouter` accepts several default options that apply globally. Configure these for consistent behavior across your application including error handling, scroll restoration, and performance optimizations.
+
+## Bad Example
+
+```tsx
+// Minimal router - missing useful defaults
+const router = createRouter({
+  routeTree,
+  context: { queryClient },
+});
+
+// Each route must handle its own errors
+// No scroll restoration on navigation
+// No preloading configured
+```
+
+## Good Example: Full Configuration
+
+```tsx
+import { QueryClient } from "@tanstack/react-query";
+import { createRouter } from "@tanstack/react-router";
+import { setupRouterSsrQueryIntegration } from "@tanstack/react-router-ssr-query";
+import { routeTree } from "./routeTree.gen";
+import { DefaultCatchBoundary } from "@/components/DefaultCatchBoundary";
+import { DefaultNotFound } from "@/components/DefaultNotFound";
+
+export function getRouter() {
+  const queryClient = new QueryClient({
+    defaultOptions: {
+      queries: {
+        refetchOnWindowFocus: false,
+        staleTime: 1000 * 60 * 2,
+      },
+    },
+  });
+
+  const router = createRouter({
+    routeTree,
+    context: { queryClient, user: null },
+
+    // Preloading
+    defaultPreload: "intent", // Preload on hover/focus
+    defaultPreloadStaleTime: 0, // Let Query manage freshness
+
+    // Error handling
+    defaultErrorComponent: DefaultCatchBoundary,
+    defaultNotFoundComponent: DefaultNotFound,
+
+    // UX
+    scrollRestoration: true, // Restore scroll on back/forward
+
+    // Performance
+    defaultStructuralSharing: true, // Optimize re-renders
+  });
+
+  setupRouterSsrQueryIntegration({
+    router,
+    queryClient,
+  });
+
+  return router;
+}
+```
+
+## Good Example: DefaultCatchBoundary Component
+
+```tsx
+// components/DefaultCatchBoundary.tsx
+import { ErrorComponent, useRouter } from "@tanstack/react-router";
+
+export function DefaultCatchBoundary({ error }: { error: Error }) {
+  const router = useRouter();
+
+  return (
+    <div className="error-container">
+      <h1>Something went wrong</h1>
+      <ErrorComponent error={error} />
+      <button onClick={() => router.invalidate()}>Try again</button>
+    </div>
+  );
+}
+```
+
+## Good Example: DefaultNotFound Component
+
+```tsx
+// components/DefaultNotFound.tsx
+import { Link } from "@tanstack/react-router";
+
+export function DefaultNotFound() {
+  return (
+    <div className="not-found-container">
+      <h1>404 - Page Not Found</h1>
+      <p>The page you're looking for doesn't exist.</p>
+      <Link to="/">Go home</Link>
+    </div>
+  );
+}
+```
+
+## Router Options Reference
+
+| Option                     | Type                                          | Default  | Description                              |
+| -------------------------- | --------------------------------------------- | -------- | ---------------------------------------- |
+| `defaultPreload`           | `false \| 'intent' \| 'render' \| 'viewport'` | `false`  | When to preload routes                   |
+| `defaultPreloadStaleTime`  | `number`                                      | `30000`  | How long preloaded data stays fresh (ms) |
+| `defaultErrorComponent`    | `Component`                                   | Built-in | Global error boundary                    |
+| `defaultNotFoundComponent` | `Component`                                   | Built-in | Global 404 page                          |
+| `scrollRestoration`        | `boolean`                                     | `false`  | Restore scroll on navigation             |
+| `defaultStructuralSharing` | `boolean`                                     | `true`   | Optimize loader data re-renders          |
+
+## Good Example: Route-Level Overrides
+
+```tsx
+// Routes can override defaults
+export const Route = createFileRoute("/admin")({
+  // Custom error handling for admin section
+  errorComponent: AdminErrorBoundary,
+  notFoundComponent: AdminNotFound,
+
+  // Disable preload for sensitive routes
+  preload: false,
+});
+```
+
+## Good Example: With Pending Component
+
+```tsx
+const router = createRouter({
+  routeTree,
+  context: { queryClient },
+
+  defaultPreload: "intent",
+  defaultPreloadStaleTime: 0,
+  defaultErrorComponent: DefaultCatchBoundary,
+  defaultNotFoundComponent: DefaultNotFound,
+  scrollRestoration: true,
+
+  // Show during route transitions
+  defaultPendingComponent: () => <div className="loading-bar" />,
+  defaultPendingMinMs: 200, // Min time to show pending UI
+  defaultPendingMs: 1000, // Delay before showing pending UI
+});
+```
+
+## Context
+
+- Set `defaultPreloadStaleTime: 0` when using TanStack Query
+- `scrollRestoration: true` improves back/forward navigation UX
+- `defaultStructuralSharing` prevents unnecessary re-renders
+- Route-level options override router defaults
+- Error/NotFound components receive route context
+- Pending components help with perceived performance

package/vendor/skills/skills/tanstack-router-best-practices/rules/search-custom-serializer.md

@@ -0,0 +1,198 @@
+# search-custom-serializer: Configure Custom Search Param Serializers
+
+## Priority: LOW
+
+## Explanation
+
+By default, TanStack Router serializes search params as JSON. For cleaner URLs or compatibility with external systems, you can provide custom serializers using libraries like `qs`, `query-string`, or your own implementation.
+
+## Bad Example
+
+```tsx
+// Default JSON serialization creates ugly URLs
+// URL: /products?filters=%7B%22category%22%3A%22electronics%22%2C%22inStock%22%3Atrue%7D
+
+// Or manually parsing/serializing inconsistently
+function ProductList() {
+  const searchParams = new URLSearchParams(window.location.search);
+  const filters = JSON.parse(searchParams.get("filters") || "{}");
+  // Inconsistent with router's handling
+}
+```
+
+## Good Example: Using JSURL for Compact URLs
+
+```tsx
+import { createRouter } from "@tanstack/react-router";
+import JSURL from "jsurl2";
+
+const router = createRouter({
+  routeTree,
+  search: {
+    // Custom serializer for compact, URL-safe encoding
+    serialize: search => JSURL.stringify(search),
+    parse: searchString => JSURL.parse(searchString) || {},
+  },
+});
+
+// URL: /products?~(category~'electronics~inStock~true)
+// Much shorter than JSON!
+```
+
+## Good Example: Using query-string for Flat Params
+
+```tsx
+import { createRouter } from "@tanstack/react-router";
+import queryString from "query-string";
+
+const router = createRouter({
+  routeTree,
+  search: {
+    serialize: search =>
+      queryString.stringify(search, {
+        arrayFormat: "bracket",
+        skipNull: true,
+      }),
+    parse: searchString =>
+      queryString.parse(searchString, {
+        arrayFormat: "bracket",
+        parseBooleans: true,
+        parseNumbers: true,
+      }),
+  },
+});
+
+// URL: /products?category=electronics&inStock=true&tags[]=sale&tags[]=new
+// Traditional query string format
+```
+
+## Good Example: Using qs for Nested Objects
+
+```tsx
+import { createRouter } from "@tanstack/react-router";
+import qs from "qs";
+
+const router = createRouter({
+  routeTree,
+  search: {
+    serialize: search =>
+      qs.stringify(search, {
+        encodeValuesOnly: true,
+        arrayFormat: "brackets",
+      }),
+    parse: searchString =>
+      qs.parse(searchString, {
+        ignoreQueryPrefix: true,
+        decoder(value) {
+          // Parse booleans and numbers
+          if (value === "true") return true;
+          if (value === "false") return false;
+          if (/^-?\d+$/.test(value)) return parseInt(value, 10);
+          return value;
+        },
+      }),
+  },
+});
+
+// URL: /products?filters[category]=electronics&filters[price][min]=100&filters[price][max]=500
+```
+
+## Good Example: Base64 for Complex State
+
+```tsx
+import { createRouter } from "@tanstack/react-router";
+
+const router = createRouter({
+  routeTree,
+  search: {
+    serialize: search => {
+      if (Object.keys(search).length === 0) return "";
+      const json = JSON.stringify(search);
+      return btoa(json); // Base64 encode
+    },
+    parse: searchString => {
+      if (!searchString) return {};
+      try {
+        return JSON.parse(atob(searchString)); // Base64 decode
+      } catch {
+        return {};
+      }
+    },
+  },
+});
+
+// URL: /products?eyJjYXRlZ29yeSI6ImVsZWN0cm9uaWNzIn0
+// Opaque but compact
+```
+
+## Good Example: Hybrid Approach
+
+```tsx
+// Some params as regular query, complex ones as JSON
+import { createRouter } from "@tanstack/react-router";
+
+const router = createRouter({
+  routeTree,
+  search: {
+    serialize: search => {
+      const { filters, ...simple } = search;
+      const params = new URLSearchParams();
+
+      // Simple values as regular params
+      Object.entries(simple).forEach(([key, value]) => {
+        if (value !== undefined) {
+          params.set(key, String(value));
+        }
+      });
+
+      // Complex filters as JSON
+      if (filters && Object.keys(filters).length > 0) {
+        params.set("filters", JSON.stringify(filters));
+      }
+
+      return params.toString();
+    },
+    parse: searchString => {
+      const params = new URLSearchParams(searchString);
+      const result: Record<string, unknown> = {};
+
+      params.forEach((value, key) => {
+        if (key === "filters") {
+          result.filters = JSON.parse(value);
+        } else if (value === "true") {
+          result[key] = true;
+        } else if (value === "false") {
+          result[key] = false;
+        } else if (/^-?\d+$/.test(value)) {
+          result[key] = parseInt(value, 10);
+        } else {
+          result[key] = value;
+        }
+      });
+
+      return result;
+    },
+  },
+});
+
+// URL: /products?page=1&sort=price&filters={"category":"electronics","inStock":true}
+```
+
+## Serializer Comparison
+
+| Library        | URL Style               | Best For          |
+| -------------- | ----------------------- | ----------------- |
+| Default (JSON) | `?data=%7B...%7D`       | TypeScript safety |
+| jsurl2         | `?~(key~'value)`        | Compact, readable |
+| query-string   | `?key=value&arr[]=1`    | Traditional APIs  |
+| qs             | `?obj[nested]=value`    | Deep nesting      |
+| Base64         | `?eyJrZXkiOiJ2YWx1ZSJ9` | Opaque, compact   |
+
+## Context
+
+- Custom serializers apply globally to all routes
+- Route-level `validateSearch` still works after parsing
+- Consider URL length limits (~2000 chars for safe cross-browser)
+- SEO: Search engines may not understand custom formats
+- Bookmarkability: Users can't easily modify opaque URLs
+- Debugging: JSON is easier to read in browser devtools