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

package/scaffold/.agents/skills/tanstack-query/references/lifecycle/migrate-major-versions-and-codemods.md

@@ -0,0 +1,169 @@
+---
+name: lifecycle/migrate-major-versions-and-codemods
+description: >
+  Use this when migrating TanStack Query across React Query v3, React Query v4,
+  TanStack Query v5, Vue Query v5, Svelte Query v6, removed overloads,
+  object syntax, cacheTime to gcTime, removed query callbacks, keepPreviousData
+  migration, and query-codemods.
+type: lifecycle
+library: TanStack Query
+library_version: "5.101.0"
+sources:
+  - TanStack/query:docs/framework/react/guides/migrating-to-react-query-3.md
+  - TanStack/query:docs/framework/react/guides/migrating-to-react-query-4.md
+  - TanStack/query:docs/framework/react/guides/migrating-to-v5.md
+  - TanStack/query:docs/framework/vue/guides/migrating-to-v5.md
+  - TanStack/query:docs/framework/svelte/migrate-from-v5-to-v6.md
+  - TanStack/query:packages/query-codemods/package.json
+---
+
+## Setup
+
+```ts
+import { useQuery } from "@tanstack/react-query";
+
+export function useTodos() {
+  return useQuery({
+    queryKey: ["todos"],
+    queryFn: async () => [{ id: 1 }],
+    gcTime: 5 * 60 * 1000,
+  });
+}
+```
+
+## Core Patterns
+
+### Use object syntax everywhere
+
+```ts
+import { QueryClient, useQuery } from "@tanstack/react-query";
+
+const queryClient = new QueryClient();
+
+export function useTodo(id: string) {
+  return useQuery({ queryKey: ["todo", id], queryFn: async () => ({ id }) });
+}
+
+export function prefetchTodo(id: string) {
+  return queryClient.prefetchQuery({
+    queryKey: ["todo", id],
+    queryFn: async () => ({ id }),
+  });
+}
+```
+
+### Rename cacheTime to gcTime
+
+```ts
+import { QueryClient } from "@tanstack/react-query";
+
+export const queryClient = new QueryClient({
+  defaultOptions: { queries: { gcTime: 10 * 60 * 1000 } },
+});
+```
+
+### Migrate keepPreviousData
+
+```ts
+import { keepPreviousData, useQuery } from "@tanstack/react-query";
+
+export function usePage(page: number) {
+  return useQuery({
+    queryKey: ["page", page],
+    queryFn: async () => ({ page }),
+    placeholderData: keepPreviousData,
+  });
+}
+```
+
+## Common Mistakes
+
+### CRITICAL v4 overload syntax
+
+Wrong:
+
+```ts
+import { useQuery } from "@tanstack/react-query";
+
+export function useTodos() {
+  return useQuery(["todos"], async () => [{ id: 1 }]);
+}
+```
+
+Correct:
+
+```ts
+import { useQuery } from "@tanstack/react-query";
+
+export function useTodos() {
+  return useQuery({ queryKey: ["todos"], queryFn: async () => [{ id: 1 }] });
+}
+```
+
+v5 removed hook and client overloads in favor of a single object signature.
+
+Source: TanStack/query:docs/framework/react/guides/migrating-to-v5.md
+
+### HIGH Removed query callbacks
+
+Wrong:
+
+```ts
+import { useQuery } from "@tanstack/react-query";
+
+export function useTodos() {
+  return useQuery({
+    queryKey: ["todos"],
+    queryFn: async () => [{ id: 1 }],
+    onSuccess: () => console.log("loaded"),
+  });
+}
+```
+
+Correct:
+
+```tsx
+import * as React from "react";
+import { useQuery } from "@tanstack/react-query";
+
+export function TodosLogger() {
+  const { data } = useQuery({
+    queryKey: ["todos"],
+    queryFn: async () => [{ id: 1 }],
+  });
+  React.useEffect(() => {
+    if (data) console.log("loaded");
+  }, [data]);
+  return null;
+}
+```
+
+v5 removed query callbacks from queries; react to data changes outside the query options.
+
+Source: TanStack/query:docs/framework/react/guides/migrating-to-v5.md
+
+### HIGH cacheTime in v5
+
+Wrong:
+
+```ts
+import { QueryClient } from "@tanstack/react-query";
+
+export const queryClient = new QueryClient({
+  defaultOptions: { queries: { cacheTime: 60_000 } },
+});
+```
+
+Correct:
+
+```ts
+import { QueryClient } from "@tanstack/react-query";
+
+export const queryClient = new QueryClient({
+  defaultOptions: { queries: { gcTime: 60_000 } },
+});
+```
+
+`cacheTime` was renamed to `gcTime` to describe garbage collection of unused queries.
+
+Source: TanStack/query:docs/framework/react/guides/migrating-to-v5.md

package/scaffold/.agents/skills/tanstack-query/references/lifecycle/prefetch-and-remove-request-waterfalls.md

@@ -0,0 +1,228 @@
+---
+name: lifecycle/prefetch-and-remove-request-waterfalls
+description: >
+  Use this when flattening request waterfalls with prefetchQuery,
+  prefetchInfiniteQuery, ensureQueryData, fetchQuery, usePrefetchQuery,
+  usePrefetchInfiniteQuery, route loaders, TanStack Router loaders, Start routes,
+  Suspense prefetching, and query-function prefetching.
+type: lifecycle
+library: TanStack Query
+library_version: "5.101.0"
+requires:
+  - core/design-query-keys-and-options
+  - core/fetch-and-observe-queries
+  - core/tune-defaults-freshness-retries-and-refetching
+sources:
+  - TanStack/query:docs/framework/react/guides/prefetching.md
+  - TanStack/query:docs/framework/react/guides/request-waterfalls.md
+  - TanStack/query:docs/framework/react/reference/usePrefetchQuery.md
+  - TanStack/query:docs/framework/react/reference/usePrefetchInfiniteQuery.md
+  - TanStack/query:docs/reference/QueryClient.md
+  - TanStack/query:examples/react/react-router/src/routes/root.tsx
+  - TanStack/query:examples/react/react-router/src/routes/contact.tsx
+---
+
+## Setup
+
+```ts
+import { QueryClient, queryOptions } from "@tanstack/react-query";
+
+const queryClient = new QueryClient();
+
+const todosOptions = queryOptions({
+  queryKey: ["todos"],
+  queryFn: async () => [{ id: 1, title: "Ship" }],
+  staleTime: 60_000,
+});
+
+export function preloadTodos() {
+  return queryClient.prefetchQuery(todosOptions);
+}
+```
+
+## Core Patterns
+
+### Use loaders for route-critical data
+
+```ts
+import { QueryClient, queryOptions } from "@tanstack/react-query";
+
+const queryClient = new QueryClient();
+const contactOptions = (contactId: string) =>
+  queryOptions({
+    queryKey: ["contact", contactId],
+    queryFn: async () => ({ id: contactId, name: "Ada" }),
+  });
+
+export function contactLoader(contactId: string) {
+  return queryClient.ensureQueryData(contactOptions(contactId));
+}
+```
+
+### Prefetch before Suspense can suspend
+
+```tsx
+import { Suspense } from "react";
+import { usePrefetchQuery, useSuspenseQuery } from "@tanstack/react-query";
+
+const commentsOptions = {
+  queryKey: ["comments"],
+  queryFn: async () => [{ id: 1 }],
+};
+
+function Comments() {
+  const { data } = useSuspenseQuery(commentsOptions);
+  return <pre>{JSON.stringify(data)}</pre>;
+}
+
+export function CommentsSection() {
+  usePrefetchQuery(commentsOptions);
+  return (
+    <Suspense fallback={<p>Loading</p>}>
+      <Comments />
+    </Suspense>
+  );
+}
+```
+
+### Pick the right client method
+
+```ts
+import { QueryClient } from "@tanstack/react-query";
+
+const queryClient = new QueryClient();
+
+export function getTodo(id: string) {
+  return queryClient.fetchQuery({
+    queryKey: ["todo", id],
+    queryFn: async () => ({ id }),
+  });
+}
+```
+
+Use `fetchQuery` when the caller needs data or thrown errors; use `prefetchQuery` when it only needs to warm the cache.
+
+## Common Mistakes
+
+### HIGH Expecting prefetchQuery to return data
+
+Wrong:
+
+```ts
+import { QueryClient } from "@tanstack/react-query";
+
+const queryClient = new QueryClient();
+const data = await queryClient.prefetchQuery({
+  queryKey: ["todo", 1],
+  queryFn: async () => ({ id: 1 }),
+});
+```
+
+Correct:
+
+```ts
+import { QueryClient } from "@tanstack/react-query";
+
+const queryClient = new QueryClient();
+const data = await queryClient.fetchQuery({
+  queryKey: ["todo", 1],
+  queryFn: async () => ({ id: 1 }),
+});
+```
+
+`prefetchQuery` returns void and swallows errors; `fetchQuery` returns data and throws.
+
+Source: TanStack/query:docs/framework/react/guides/prefetching.md
+
+### HIGH Prefetch staleTime only set on prefetch
+
+Wrong:
+
+```ts
+import { QueryClient, useQuery } from "@tanstack/react-query";
+
+const queryClient = new QueryClient();
+await queryClient.prefetchQuery({
+  queryKey: ["todos"],
+  queryFn: async () => [{ id: 1 }],
+  staleTime: 60_000,
+});
+export function useTodos() {
+  return useQuery({ queryKey: ["todos"], queryFn: async () => [{ id: 1 }] });
+}
+```
+
+Correct:
+
+```ts
+import { QueryClient, queryOptions, useQuery } from "@tanstack/react-query";
+
+const queryClient = new QueryClient();
+const options = queryOptions({
+  queryKey: ["todos"],
+  queryFn: async () => [{ id: 1 }],
+  staleTime: 60_000,
+});
+await queryClient.prefetchQuery(options);
+export function useTodos() {
+  return useQuery(options);
+}
+```
+
+Prefetch call options do not automatically configure the later observer.
+
+Source: TanStack/query:docs/framework/react/guides/prefetching.md
+
+### HIGH Suspense prefetch after suspension
+
+Wrong:
+
+```tsx
+import * as React from "react";
+import { useQueryClient, useSuspenseQuery } from "@tanstack/react-query";
+
+export function Article() {
+  const queryClient = useQueryClient();
+  const article = useSuspenseQuery({
+    queryKey: ["article"],
+    queryFn: async () => ({ id: 1 }),
+  });
+  React.useEffect(() => {
+    queryClient.prefetchQuery({
+      queryKey: ["comments"],
+      queryFn: async () => [],
+    });
+  }, [queryClient]);
+  return <pre>{JSON.stringify(article.data)}</pre>;
+}
+```
+
+Correct:
+
+```tsx
+import { Suspense } from "react";
+import { usePrefetchQuery, useSuspenseQuery } from "@tanstack/react-query";
+
+function Article() {
+  const article = useSuspenseQuery({
+    queryKey: ["article"],
+    queryFn: async () => ({ id: 1 }),
+  });
+  return <pre>{JSON.stringify(article.data)}</pre>;
+}
+
+export function ArticleRoute() {
+  usePrefetchQuery({ queryKey: ["comments"], queryFn: async () => [] });
+  return (
+    <Suspense fallback={<p>Loading</p>}>
+      <Article />
+    </Suspense>
+  );
+}
+```
+
+Effects do not run until after a suspenseful query resolves, so they cannot flatten that waterfall.
+
+Source: TanStack/query:docs/framework/react/guides/prefetching.md
+
+See also: `compositions/compose-query-with-tanstack-router-and-start` for Router and Start loader prefetching.

package/scaffold/.agents/skills/tanstack-query/references/lifecycle/setup-query-client-and-providers.md

@@ -0,0 +1,161 @@
+---
+name: lifecycle/setup-query-client-and-providers
+description: >
+  Use this when creating a TanStack Query QueryClient, QueryClientProvider, VueQueryPlugin,
+  provideTanStackQuery, Svelte QueryClientProvider, Angular providers, Lit controllers, or
+  SSR request-local clients. Covers stable client lifetime and provider wiring.
+type: lifecycle
+library: TanStack Query
+library_version: "5.101.0"
+sources:
+  - TanStack/query:docs/framework/react/quick-start.md
+  - TanStack/query:docs/framework/react/reference/QueryClientProvider.md
+  - TanStack/query:docs/eslint/stable-query-client.md
+  - TanStack/query:docs/framework/vue/guides/custom-client.md
+  - TanStack/query:docs/framework/angular/overview.md
+  - TanStack/query:docs/framework/lit/guides/reactive-controllers-vs-hooks.md
+---
+
+## Setup
+
+```tsx
+import * as React from "react";
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+
+export function AppProviders(props: { children: React.ReactNode }) {
+  const [queryClient] = React.useState(() => new QueryClient());
+  return <QueryClientProvider client={queryClient}>{props.children}</QueryClientProvider>;
+}
+```
+
+## Core Patterns
+
+### Create request-local SSR clients
+
+```ts
+import { QueryClient } from "@tanstack/react-query";
+
+export function createServerQueryClient() {
+  return new QueryClient({
+    defaultOptions: { queries: { staleTime: 60_000 } },
+  });
+}
+```
+
+### Use adapter-native providers
+
+```ts
+import { QueryClient } from "@tanstack/query-core";
+
+export function createQueryClient() {
+  return new QueryClient({
+    defaultOptions: { queries: { retry: 2 } },
+  });
+}
+```
+
+React and Preact use `QueryClientProvider`; Vue uses `VueQueryPlugin`; Angular uses `provideTanStackQuery`; Svelte and Lit use their adapter provider/controller APIs.
+
+### Pass an explicit client at integration boundaries
+
+```ts
+import { QueryClient } from "@tanstack/query-core";
+
+const queryClient = new QueryClient();
+
+export function getTodos() {
+  return queryClient.ensureQueryData({
+    queryKey: ["todos"],
+    queryFn: async () => [{ id: 1, title: "Ship" }],
+  });
+}
+```
+
+## Common Mistakes
+
+### CRITICAL New client on every render
+
+Wrong:
+
+```tsx
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+
+export function App(props: { children: React.ReactNode }) {
+  const queryClient = new QueryClient();
+  return <QueryClientProvider client={queryClient}>{props.children}</QueryClientProvider>;
+}
+```
+
+Correct:
+
+```tsx
+import * as React from "react";
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+
+export function App(props: { children: React.ReactNode }) {
+  const [queryClient] = React.useState(() => new QueryClient());
+  return <QueryClientProvider client={queryClient}>{props.children}</QueryClientProvider>;
+}
+```
+
+Recreating the client discards caches and subscriptions on render.
+
+Source: TanStack/query:docs/eslint/stable-query-client.md
+
+### CRITICAL Shared SSR cache between users
+
+Wrong:
+
+```ts
+import { QueryClient } from "@tanstack/react-query";
+
+export const queryClient = new QueryClient();
+```
+
+Correct:
+
+```ts
+import { QueryClient } from "@tanstack/react-query";
+
+export function createRequestQueryClient() {
+  return new QueryClient();
+}
+```
+
+A module-level server client can leak one request's cached data into another request.
+
+Source: TanStack/query:docs/framework/react/guides/ssr.md
+
+### HIGH Ambiguous Lit fallback client
+
+Wrong:
+
+```ts
+import { QueryController } from "@tanstack/lit-query";
+
+export class TodoElement extends HTMLElement {
+  todos = new QueryController(this, {
+    queryKey: ["todos"],
+    queryFn: async () => [],
+  });
+}
+```
+
+Correct:
+
+```ts
+import { QueryClient } from "@tanstack/query-core";
+import { QueryController } from "@tanstack/lit-query";
+
+const queryClient = new QueryClient();
+
+export class TodoElement extends HTMLElement {
+  todos = new QueryController(this, { queryKey: ["todos"], queryFn: async () => [] }, queryClient);
+}
+```
+
+Lit controllers need a clear provider or explicit client when the element is not under a provider tree.
+
+Source: TanStack/query:docs/framework/lit/guides/reactive-controllers-vs-hooks.md
+
+See also: `lifecycle/ssr-hydration-and-streaming` for server cache handoff.