@hitch42/applet 0.1.1-beta.7 → 0.1.1-beta.9

package/scaffold/.agents/skills/tanstack-query/references/compositions/compose-query-with-tanstack-router-and-start.md

@@ -0,0 +1,248 @@
+---
+name: compositions/compose-query-with-tanstack-router-and-start
+description: >
+  Use this when combining TanStack Query with TanStack Router or TanStack Start:
+  router context QueryClient, createFileRoute loaders, ensureQueryData,
+  @tanstack/react-router-ssr-query, setupRouterSsrQueryIntegration, SSR hydration,
+  streaming, redirects, and Start server functions.
+type: composition
+library: TanStack Query
+library_version: "5.101.0"
+requires:
+  - lifecycle/setup-query-client-and-providers
+  - core/design-query-keys-and-options
+  - lifecycle/prefetch-and-remove-request-waterfalls
+sources:
+  - TanStack/router:https://tanstack.com/router/latest/docs/integrations/query
+  - TanStack/router:https://tanstack.com/router/latest/docs/how-to/setup-ssr
+  - TanStack/start:https://tanstack.com/start/latest/docs/framework/react/overview
+  - TanStack/query:docs/framework/react/guides/prefetching.md
+  - TanStack/query:docs/framework/react/guides/ssr.md
+---
+
+## Setup
+
+```tsx
+import { QueryClient, QueryClientProvider, useSuspenseQuery } from "@tanstack/react-query";
+import { createFileRoute, createRouter, RouterProvider } from "@tanstack/react-router";
+import { routeTree } from "./routeTree.gen";
+
+const queryClient = new QueryClient();
+
+const postsQuery = {
+  queryKey: ["posts"],
+  queryFn: async () => [{ id: 1, title: "Router first" }],
+};
+
+export const Route = createFileRoute("/posts")({
+  loader: ({ context }) => context.queryClient.ensureQueryData(postsQuery),
+  component: PostsPage,
+});
+
+function PostsPage() {
+  const { data } = useSuspenseQuery(postsQuery);
+  return <pre>{JSON.stringify(data)}</pre>;
+}
+
+const router = createRouter({ routeTree, context: { queryClient } });
+
+export function App() {
+  return (
+    <QueryClientProvider client={queryClient}>
+      <RouterProvider router={router} />
+    </QueryClientProvider>
+  );
+}
+```
+
+## Core Integration Patterns
+
+### Put QueryClient in router context
+
+```ts
+import { QueryClient } from "@tanstack/react-query";
+import { createRouter } from "@tanstack/react-router";
+import { routeTree } from "./routeTree.gen";
+
+const queryClient = new QueryClient();
+
+export const router = createRouter({
+  routeTree,
+  context: { queryClient },
+  defaultPreloadStaleTime: 0,
+});
+```
+
+Set `defaultPreloadStaleTime: 0` when Query owns server-state freshness. Router still preloads and runs loaders, but Query is the cache authority.
+
+### Use loader ensureQueryData for route data
+
+```ts
+import { createFileRoute } from "@tanstack/react-router";
+
+const todoQuery = (todoId: string) => ({
+  queryKey: ["todo", todoId],
+  queryFn: async () => ({ id: todoId, title: "Loaded" }),
+});
+
+export const Route = createFileRoute("/todos/$todoId")({
+  loader: ({ context, params }) => context.queryClient.ensureQueryData(todoQuery(params.todoId)),
+});
+```
+
+Treat loaders as event handlers that prime the Query cache. Components should still call `useQuery` or `useSuspenseQuery` so the route has an active Query observer.
+
+### Prefer Router SSR Query integration for Router SSR
+
+```ts
+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";
+
+const queryClient = new QueryClient();
+const router = createRouter({ routeTree, context: { queryClient } });
+
+setupRouterSsrQueryIntegration({ router, queryClient });
+```
+
+## Common Mistakes
+
+### CRITICAL Component-only Query creates route waterfall
+
+Wrong:
+
+```tsx
+import { createFileRoute } from "@tanstack/react-router";
+import { useSuspenseQuery } from "@tanstack/react-query";
+
+export const Route = createFileRoute("/posts")({ component: PostsPage });
+function PostsPage() {
+  const { data } = useSuspenseQuery({
+    queryKey: ["posts"],
+    queryFn: async () => [{ id: 1 }],
+  });
+  return <pre>{JSON.stringify(data)}</pre>;
+}
+```
+
+Correct:
+
+```tsx
+import { createFileRoute } from "@tanstack/react-router";
+import { useSuspenseQuery } from "@tanstack/react-query";
+
+const postsQuery = { queryKey: ["posts"], queryFn: async () => [{ id: 1 }] };
+export const Route = createFileRoute("/posts")({
+  loader: ({ context }) => context.queryClient.ensureQueryData(postsQuery),
+  component: PostsPage,
+});
+function PostsPage() {
+  const { data } = useSuspenseQuery(postsQuery);
+  return <pre>{JSON.stringify(data)}</pre>;
+}
+```
+
+The router can load route-critical data before component render.
+
+Source: TanStack/router:https://tanstack.com/router/latest/docs/integrations/query
+
+### CRITICAL Hand-rolled Router hydration
+
+Wrong:
+
+```tsx
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import { createRouter, RouterProvider } from "@tanstack/react-router";
+import { routeTree } from "./routeTree.gen";
+
+const queryClient = new QueryClient();
+const router = createRouter({ routeTree });
+export function App() {
+  return (
+    <QueryClientProvider client={queryClient}>
+      <RouterProvider router={router} />
+    </QueryClientProvider>
+  );
+}
+```
+
+Correct:
+
+```ts
+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";
+
+const queryClient = new QueryClient();
+const router = createRouter({ routeTree, context: { queryClient } });
+setupRouterSsrQueryIntegration({ router, queryClient });
+```
+
+The Router SSR Query integration handles dehydration, hydration, streamed query results, redirects, and provider wrapping.
+
+Source: TanStack/router:https://tanstack.com/router/latest/docs/integrations/query
+
+### HIGH Next.js mental model copied into Start
+
+Wrong:
+
+```tsx
+export default async function Page() {
+  const posts = await Promise.resolve([{ id: 1 }]);
+  return <pre>{JSON.stringify(posts)}</pre>;
+}
+```
+
+Correct:
+
+```tsx
+import { createFileRoute } from "@tanstack/react-router";
+
+export const Route = createFileRoute("/posts")({
+  loader: ({ context }) =>
+    context.queryClient.ensureQueryData({
+      queryKey: ["posts"],
+      queryFn: async () => [{ id: 1 }],
+    }),
+  component: () => <p>Posts loaded by the route</p>,
+});
+```
+
+Start is powered by TanStack Router; use file routes, loaders, server functions, and Router SSR before Next-specific app/pages APIs.
+
+Source: TanStack/start:https://tanstack.com/start/latest/docs/framework/react/overview
+
+### HIGH Reading loader data instead of observing Query
+
+Wrong:
+
+```tsx
+import { createFileRoute, useLoaderData } from "@tanstack/react-router";
+
+export const Route = createFileRoute("/posts")({
+  loader: ({ context }) => context.queryClient.ensureQueryData(postsQuery),
+  component: PostsPage,
+});
+
+function PostsPage() {
+  const posts = useLoaderData({ from: "/posts" });
+  return <pre>{JSON.stringify(posts)}</pre>;
+}
+```
+
+Correct:
+
+```tsx
+import { useSuspenseQuery } from "@tanstack/react-query";
+
+function PostsPage() {
+  const { data } = useSuspenseQuery(postsQuery);
+  return <pre>{JSON.stringify(data)}</pre>;
+}
+```
+
+The loader primes the cache. The component still needs an active Query observer for refetch triggers, invalidation, and garbage collection semantics.
+
+See also: `lifecycle/ssr-hydration-and-streaming` for framework SSR recipes.

package/scaffold/.agents/skills/tanstack-query/references/compositions/enforce-query-best-practices-with-eslint.md

@@ -0,0 +1,167 @@
+---
+name: compositions/enforce-query-best-practices-with-eslint
+description: >
+  Use this when configuring @tanstack/eslint-plugin-query, flat/recommended,
+  flat/recommended-strict, exhaustive-deps, no-rest-destructuring,
+  no-unstable-deps, no-void-query-fn, stable-query-client, prefer-query-options,
+  infinite-query-property-order, and mutation-property-order.
+type: composition
+library: TanStack Query
+library_version: "5.101.0"
+requires:
+  - core/design-query-keys-and-options
+  - core/fetch-and-observe-queries
+  - framework/shape-data-and-render-efficiently
+sources:
+  - TanStack/query:docs/eslint/eslint-plugin-query.md
+  - TanStack/query:docs/eslint/exhaustive-deps.md
+  - TanStack/query:docs/eslint/no-rest-destructuring.md
+  - TanStack/query:docs/eslint/no-unstable-deps.md
+  - TanStack/query:docs/eslint/no-void-query-fn.md
+  - TanStack/query:docs/eslint/prefer-query-options.md
+  - TanStack/query:docs/eslint/stable-query-client.md
+  - TanStack/query:docs/eslint/infinite-query-property-order.md
+  - TanStack/query:docs/eslint/mutation-property-order.md
+---
+
+## Setup
+
+```js
+import pluginQuery from "@tanstack/eslint-plugin-query";
+
+export default [...pluginQuery.configs["flat/recommended"]];
+```
+
+## Core Integration Patterns
+
+### Use strict when generating Query-heavy code
+
+```js
+import pluginQuery from "@tanstack/eslint-plugin-query";
+
+export default [...pluginQuery.configs["flat/recommended-strict"]];
+```
+
+### Prefer option factories
+
+```ts
+import { queryOptions, useQuery } from "@tanstack/react-query";
+
+const todosOptions = queryOptions({
+  queryKey: ["todos"],
+  queryFn: async () => [{ id: 1 }],
+});
+
+export function useTodos() {
+  return useQuery(todosOptions);
+}
+```
+
+### Keep inference-sensitive property order
+
+```ts
+import { useInfiniteQuery } from "@tanstack/react-query";
+
+export function useFeed() {
+  return useInfiniteQuery({
+    queryKey: ["feed"],
+    queryFn: async ({ pageParam }) => ({ nextCursor: pageParam + 1 }),
+    initialPageParam: 0,
+    getNextPageParam: (page) => page.nextCursor,
+  });
+}
+```
+
+## Common Mistakes
+
+### MEDIUM Strict rule not enabled
+
+Wrong:
+
+```js
+import pluginQuery from "@tanstack/eslint-plugin-query";
+
+export default [...pluginQuery.configs["flat/recommended"]];
+```
+
+Correct:
+
+```js
+import pluginQuery from "@tanstack/eslint-plugin-query";
+
+export default [...pluginQuery.configs["flat/recommended-strict"]];
+```
+
+Strict mode catches option-factory and inference patterns that agents commonly miss.
+
+Source: TanStack/query:docs/eslint/eslint-plugin-query.md
+
+### MEDIUM Infinite option property order
+
+Wrong:
+
+```ts
+import { useInfiniteQuery } from "@tanstack/react-query";
+
+export function useFeed() {
+  return useInfiniteQuery({
+    queryFn: async () => ({ nextCursor: 1 }),
+    queryKey: ["feed"],
+    getNextPageParam: (page) => page.nextCursor,
+    initialPageParam: 0,
+  });
+}
+```
+
+Correct:
+
+```ts
+import { useInfiniteQuery } from "@tanstack/react-query";
+
+export function useFeed() {
+  return useInfiniteQuery({
+    queryKey: ["feed"],
+    queryFn: async ({ pageParam }) => ({ nextCursor: pageParam + 1 }),
+    initialPageParam: 0,
+    getNextPageParam: (page) => page.nextCursor,
+  });
+}
+```
+
+Some infinite-query inference depends on stable option ordering.
+
+Source: TanStack/query:docs/eslint/infinite-query-property-order.md
+
+### MEDIUM Mutation option property order
+
+Wrong:
+
+```ts
+import { useMutation } from "@tanstack/react-query";
+
+export function useSave() {
+  return useMutation({
+    onSuccess: () => console.log("saved"),
+    mutationFn: async (title: string) => title,
+  });
+}
+```
+
+Correct:
+
+```ts
+import { useMutation } from "@tanstack/react-query";
+
+export function useSave() {
+  return useMutation({
+    mutationFn: async (title: string) => title,
+    onSuccess: () => console.log("saved"),
+  });
+}
+```
+
+The mutation property order rule preserves inference for mutation options.
+
+Source: TanStack/query:docs/eslint/mutation-property-order.md
+
+See also: `core/design-query-keys-and-options` for the patterns these rules protect.

package/scaffold/.agents/skills/tanstack-query/references/compositions/persist-offline-and-restore-caches.md

@@ -0,0 +1,181 @@
+---
+name: compositions/persist-offline-and-restore-caches
+description: >
+  Use this when using persistQueryClient, PersistQueryClientProvider,
+  createSyncStoragePersister, createAsyncStoragePersister, experimental
+  fine-grained persisters, offline mutations, resumePausedMutations, maxAge,
+  gcTime, and restore races.
+type: composition
+library: TanStack Query
+library_version: "5.101.0"
+requires:
+  - lifecycle/setup-query-client-and-providers
+  - core/tune-defaults-freshness-retries-and-refetching
+  - core/write-mutations-and-invalidate-related-queries
+sources:
+  - TanStack/query:docs/framework/react/plugins/persistQueryClient.md
+  - TanStack/query:docs/framework/react/plugins/createSyncStoragePersister.md
+  - TanStack/query:docs/framework/react/plugins/createAsyncStoragePersister.md
+  - TanStack/query:docs/framework/react/plugins/createPersister.md
+  - TanStack/query:docs/framework/react/guides/network-mode.md
+---
+
+## Setup
+
+```tsx
+import * as React from "react";
+import { QueryClient } from "@tanstack/react-query";
+import { PersistQueryClientProvider } from "@tanstack/react-query-persist-client";
+import { createSyncStoragePersister } from "@tanstack/query-sync-storage-persister";
+
+const queryClient = new QueryClient({
+  defaultOptions: { queries: { gcTime: 24 * 60 * 60 * 1000 } },
+});
+
+const persister = createSyncStoragePersister({
+  storage: window.localStorage,
+});
+
+export function AppProviders(props: { children: React.ReactNode }) {
+  return (
+    <PersistQueryClientProvider client={queryClient} persistOptions={{ persister }}>
+      {props.children}
+    </PersistQueryClientProvider>
+  );
+}
+```
+
+## Core Integration Patterns
+
+### Resume paused mutations after restore
+
+```ts
+import { QueryClient } from "@tanstack/react-query";
+
+export const queryClient = new QueryClient();
+
+queryClient.setMutationDefaults(["todos"], {
+  mutationFn: async (todo: { id: number; title: string }) => todo,
+});
+
+export function resumeMutations() {
+  return queryClient.resumePausedMutations();
+}
+```
+
+### Align cache lifetime with persistence
+
+```ts
+import { QueryClient } from "@tanstack/react-query";
+
+export const queryClient = new QueryClient({
+  defaultOptions: {
+    queries: { gcTime: 7 * 24 * 60 * 60 * 1000 },
+  },
+});
+```
+
+### Use networkMode for offline-first writes
+
+```ts
+import { useMutation } from "@tanstack/react-query";
+
+export function useSaveDraft() {
+  return useMutation({
+    mutationKey: ["saveDraft"],
+    mutationFn: async (draft: { body: string }) => draft,
+    networkMode: "offlineFirst",
+  });
+}
+```
+
+## Common Mistakes
+
+### HIGH gcTime shorter than maxAge
+
+Wrong:
+
+```ts
+import { QueryClient } from "@tanstack/react-query";
+
+export const queryClient = new QueryClient({
+  defaultOptions: { queries: { gcTime: 5 * 60 * 1000 } },
+});
+```
+
+Correct:
+
+```ts
+import { QueryClient } from "@tanstack/react-query";
+
+export const queryClient = new QueryClient({
+  defaultOptions: { queries: { gcTime: 24 * 60 * 60 * 1000 } },
+});
+```
+
+Persisted data can be garbage-collected before the persister maxAge can restore it.
+
+Source: TanStack/query:docs/framework/react/plugins/persistQueryClient.md
+
+### CRITICAL Rendering before restore
+
+Wrong:
+
+```tsx
+import { QueryClientProvider, QueryClient } from "@tanstack/react-query";
+
+const queryClient = new QueryClient();
+export function App(props: { children: React.ReactNode }) {
+  return <QueryClientProvider client={queryClient}>{props.children}</QueryClientProvider>;
+}
+```
+
+Correct:
+
+```tsx
+import { QueryClient } from "@tanstack/react-query";
+import { PersistQueryClientProvider } from "@tanstack/react-query-persist-client";
+import { createSyncStoragePersister } from "@tanstack/query-sync-storage-persister";
+
+const queryClient = new QueryClient();
+const persister = createSyncStoragePersister({ storage: window.localStorage });
+
+export function App(props: { children: React.ReactNode }) {
+  return (
+    <PersistQueryClientProvider client={queryClient} persistOptions={{ persister }}>
+      {props.children}
+    </PersistQueryClientProvider>
+  );
+}
+```
+
+The persistence provider prevents query fetching while restore is in progress.
+
+Source: TanStack/query:docs/framework/react/plugins/persistQueryClient.md
+
+### CRITICAL Missing default mutationFn
+
+Wrong:
+
+```ts
+import { QueryClient } from "@tanstack/react-query";
+
+export const queryClient = new QueryClient();
+```
+
+Correct:
+
+```ts
+import { QueryClient } from "@tanstack/react-query";
+
+export const queryClient = new QueryClient();
+queryClient.setMutationDefaults(["saveDraft"], {
+  mutationFn: async (draft: { body: string }) => draft,
+});
+```
+
+Paused persisted mutations cannot resume without a serializable mutation key mapped to a default mutationFn.
+
+Source: TanStack/query:docs/framework/react/plugins/persistQueryClient.md
+
+See also: `core/tune-defaults-freshness-retries-and-refetching` for gcTime and networkMode.