npm - @jgamaraalv/ts-dev-kit - Versions diffs - 2.1.0 → 2.3.0 - Mend

@jgamaraalv/ts-dev-kit 2.1.0 → 2.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (9) hide show

package/.claude-plugin/marketplace.json +1 -1
package/.claude-plugin/plugin.json +1 -1
package/package.json +1 -1
package/skills/tanstack-query/SKILL.md +348 -0
package/skills/tanstack-query/references/advanced-patterns.md +376 -0
package/skills/tanstack-query/references/api-reference.md +297 -0
package/skills/tanstack-query/references/ssr-nextjs.md +272 -0
package/skills/tanstack-query/references/testing.md +175 -0
package/skills/task/SKILL.md +41 -40

package/skills/tanstack-query/references/ssr-nextjs.md ADDED Viewed

@@ -0,0 +1,272 @@
+# TanStack Query v5 — SSR & Next.js
+## Table of Contents
+- [Core Concept](#core-concept)
+- [Next.js Pages Router](#nextjs-pages-router)
+- [Next.js App Router](#nextjs-app-router)
+- [Streaming](#streaming)
+- [Critical Gotchas](#critical-gotchas)
+## Core Concept
+Server rendering with TanStack Query follows three steps:
+1. **Prefetch** data on the server with `queryClient.prefetchQuery()`
+2. **Dehydrate** the cache with `dehydrate(queryClient)`
+3. **Hydrate** on the client with `<HydrationBoundary state={dehydratedState}>`
+## Next.js Pages Router
+### getStaticProps / getServerSideProps
+```tsx
+import { dehydrate, QueryClient } from '@tanstack/react-query'
+export async function getStaticProps() {
+  const queryClient = new QueryClient()
+  await queryClient.prefetchQuery({
+    queryKey: ['posts'],
+    queryFn: getPosts,
+  })
+  return {
+    props: {
+      dehydratedState: dehydrate(queryClient),
+    },
+  }
+}
+```
+### _app.tsx setup
+```tsx
+import { HydrationBoundary, QueryClient, QueryClientProvider } from '@tanstack/react-query'
+import { useState } from 'react'
+export default function MyApp({ Component, pageProps }) {
+  const [queryClient] = useState(() => new QueryClient({
+    defaultOptions: {
+      queries: { staleTime: 60 * 1000 },
+    },
+  }))
+  return (
+    <QueryClientProvider client={queryClient}>
+      <HydrationBoundary state={pageProps.dehydratedState}>
+        <Component {...pageProps} />
+      </HydrationBoundary>
+    </QueryClientProvider>
+  )
+}
+```
+### Page component — uses useQuery normally
+```tsx
+export default function PostsPage() {
+  const { data } = useQuery({ queryKey: ['posts'], queryFn: getPosts })
+  // data is immediately available from the hydrated cache
+}
+```
+## Next.js App Router
+### Provider setup (app/providers.tsx)
+```tsx
+'use client'
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query'
+import { useState } from 'react'
+function makeQueryClient() {
+  return new QueryClient({
+    defaultOptions: {
+      queries: {
+        staleTime: 60 * 1000, // must be > 0 for SSR
+      },
+    },
+  })
+}
+let browserQueryClient: QueryClient | undefined
+function getQueryClient() {
+  if (typeof window === 'undefined') {
+    // Server: always make a new query client
+    return makeQueryClient()
+  }
+  // Browser: reuse singleton
+  if (!browserQueryClient) browserQueryClient = makeQueryClient()
+  return browserQueryClient
+}
+export default function Providers({ children }: { children: React.ReactNode }) {
+  const queryClient = getQueryClient()
+  return (
+    <QueryClientProvider client={queryClient}>
+      {children}
+    </QueryClientProvider>
+  )
+}
+```
+**Why not `useState`?** If there is no Suspense boundary between the provider and suspending code, React throws away state on initial suspend. The singleton pattern avoids losing the client.
+### Root layout (app/layout.tsx)
+```tsx
+import Providers from './providers'
+export default function RootLayout({ children }: { children: React.ReactNode }) {
+  return (
+    <html>
+      <body>
+        <Providers>{children}</Providers>
+      </body>
+    </html>
+  )
+}
+```
+### Prefetch in Server Components
+```tsx
+// app/posts/page.tsx (Server Component)
+import { dehydrate, HydrationBoundary, QueryClient } from '@tanstack/react-query'
+import Posts from './posts' // Client Component
+export default async function PostsPage() {
+  const queryClient = new QueryClient()
+  await queryClient.prefetchQuery({
+    queryKey: ['posts'],
+    queryFn: getPosts,
+  })
+  return (
+    <HydrationBoundary state={dehydrate(queryClient)}>
+      <Posts />
+    </HydrationBoundary>
+  )
+}
+```
+```tsx
+// app/posts/posts.tsx (Client Component)
+'use client'
+import { useQuery } from '@tanstack/react-query'
+export default function Posts() {
+  const { data } = useQuery({ queryKey: ['posts'], queryFn: getPosts })
+  // data is available immediately from hydration
+}
+```
+### Nested prefetching
+Multiple `<HydrationBoundary>` with separate queryClients at different levels is fine. Deeply nested Server Components can each prefetch their own data.
+### Shared queryClient with React.cache
+```tsx
+import { cache } from 'react'
+const getQueryClient = cache(() => new QueryClient())
+// Any Server Component in the same request:
+export default async function Page() {
+  const queryClient = getQueryClient()
+  await queryClient.prefetchQuery({ queryKey: ['posts'], queryFn: getPosts })
+  return (
+    <HydrationBoundary state={dehydrate(queryClient)}>
+      <Posts />
+    </HydrationBoundary>
+  )
+}
+```
+Downside: each `dehydrate()` serializes the entire cache, including previously serialized queries.
+## Streaming
+Available since v5.40.0. Pending queries can be dehydrated and streamed without `await`.
+### Setup — configure dehydration to include pending queries
+```tsx
+function makeQueryClient() {
+  return new QueryClient({
+    defaultOptions: {
+      queries: { staleTime: 60 * 1000 },
+      dehydrate: {
+        shouldDehydrateQuery: (query) =>
+          defaultShouldDehydrateQuery(query) || query.state.status === 'pending',
+      },
+    },
+  })
+}
+```
+### Stream prefetch (no await)
+```tsx
+// app/posts/page.tsx
+export default function PostsPage() {
+  const queryClient = new QueryClient()
+  // No await — query starts but doesn't block rendering
+  queryClient.prefetchQuery({ queryKey: ['posts'], queryFn: getPosts })
+  return (
+    <HydrationBoundary state={dehydrate(queryClient)}>
+      <Posts />
+    </HydrationBoundary>
+  )
+}
+```
+On the client, use `useSuspenseQuery` to consume the streamed promise:
+```tsx
+'use client'
+export default function Posts() {
+  const { data } = useSuspenseQuery({ queryKey: ['posts'], queryFn: getPosts })
+  // Suspends until streamed data arrives, then renders
+}
+```
+### Non-JSON serialization
+For data with Dates, Maps, etc., configure custom serialization:
+```tsx
+defaultOptions: {
+  dehydrate: { serializeData: superjson.serialize },
+  hydrate: { deserializeData: superjson.deserialize },
+}
+```
+## Critical Gotchas
+1. **Never create QueryClient at module scope** — it leaks data between requests/users:
+   ```tsx
+   // WRONG
+   const queryClient = new QueryClient()
+   export default function App() { ... }
+   // CORRECT
+   const [queryClient] = useState(() => new QueryClient())
+   ```
+2. **Set `staleTime > 0` for SSR** — with default `staleTime: 0`, the client immediately refetches on mount, negating the prefetch.
+3. **Don't use `fetchQuery` in Server Components to render data** — if both a Server Component and a Client Component use the same data, they desync when the client revalidates. Use `prefetchQuery` (which only populates the cache) and let client components own the data rendering.
+4. **`hydrate` only overwrites if incoming data is newer** — checked by timestamp.
+5. **`Error` objects and `undefined` are not JSON-serializable** — handle serialization manually if dehydrating errors. By default, errors are redacted (replaced with `null`).
+6. **Data ownership rule:** The component that renders the data should own it. Server Components prefetch; Client Components consume via `useQuery`/`useSuspenseQuery`.

package/skills/tanstack-query/references/testing.md ADDED Viewed

@@ -0,0 +1,175 @@
+# TanStack Query v5 — Testing
+## Setup
+Use `@testing-library/react` (v14+) directly — no need for `@testing-library/react-hooks`.
+### Create a wrapper with isolated QueryClient
+```tsx
+import { renderHook, waitFor } from '@testing-library/react'
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query'
+import type { ReactNode } from 'react'
+function createTestQueryClient() {
+  return new QueryClient({
+    defaultOptions: {
+      queries: {
+        retry: false,  // CRITICAL: disable retries in tests
+      },
+    },
+  })
+}
+function createWrapper() {
+  const queryClient = createTestQueryClient()
+  return function Wrapper({ children }: { children: ReactNode }) {
+    return (
+      <QueryClientProvider client={queryClient}>
+        {children}
+      </QueryClientProvider>
+    )
+  }
+}
+```
+## Testing a Custom Hook
+```tsx
+// hooks/useTodos.ts
+export function useTodos() {
+  return useQuery({ queryKey: ['todos'], queryFn: fetchTodos })
+}
+// hooks/useTodos.test.ts
+import { renderHook, waitFor } from '@testing-library/react'
+import { useTodos } from './useTodos'
+test('fetches todos', async () => {
+  const { result } = renderHook(() => useTodos(), {
+    wrapper: createWrapper(),
+  })
+  await waitFor(() => expect(result.current.isSuccess).toBe(true))
+  expect(result.current.data).toEqual([{ id: 1, title: 'Test' }])
+})
+```
+## Network Mocking
+### With nock
+```tsx
+import nock from 'nock'
+test('fetches data from API', async () => {
+  nock('http://example.com')
+    .get('/api/todos')
+    .reply(200, [{ id: 1, title: 'Test' }])
+  const { result } = renderHook(() => useTodos(), {
+    wrapper: createWrapper(),
+  })
+  await waitFor(() => expect(result.current.isSuccess).toBe(true))
+  expect(result.current.data).toEqual([{ id: 1, title: 'Test' }])
+})
+```
+### With msw (recommended)
+```tsx
+import { setupServer } from 'msw/node'
+import { http, HttpResponse } from 'msw'
+const server = setupServer(
+  http.get('/api/todos', () =>
+    HttpResponse.json([{ id: 1, title: 'Test' }])
+  ),
+)
+beforeAll(() => server.listen())
+afterEach(() => server.resetHandlers())
+afterAll(() => server.close())
+```
+## Testing Infinite Queries
+```tsx
+import nock from 'nock'
+test('fetches multiple pages', async () => {
+  const expectation = nock('http://example.com')
+    .persist()  // .persist() for multiple requests
+    .query(true)
+    .get('/api/items')
+    .reply(200, (uri) => {
+      const url = new URL(`http://example.com${uri}`)
+      const page = url.searchParams.get('page') ?? '1'
+      return { items: [`item-${page}`], nextPage: Number(page) < 3 ? Number(page) + 1 : null }
+    })
+  const { result } = renderHook(() => useInfiniteItems(), {
+    wrapper: createWrapper(),
+  })
+  await waitFor(() => expect(result.current.isSuccess).toBe(true))
+  expect(result.current.data.pages).toHaveLength(1)
+  // Fetch next page
+  result.current.fetchNextPage()
+  await waitFor(() => expect(result.current.data.pages).toHaveLength(2))
+})
+```
+## Testing Mutations
+```tsx
+test('creates a todo and invalidates list', async () => {
+  const queryClient = createTestQueryClient()
+  const wrapper = ({ children }: { children: ReactNode }) => (
+    <QueryClientProvider client={queryClient}>{children}</QueryClientProvider>
+  )
+  // Pre-populate cache
+  queryClient.setQueryData(['todos'], [{ id: 1, title: 'Existing' }])
+  const { result } = renderHook(() => useCreateTodo(), { wrapper })
+  result.current.mutate({ title: 'New Todo' })
+  await waitFor(() => expect(result.current.isSuccess).toBe(true))
+})
+```
+## Key Gotchas
+1. **Always disable retries** — Default 3 retries with exponential backoff causes test timeouts:
+   ```tsx
+   new QueryClient({ defaultOptions: { queries: { retry: false } } })
+   ```
+   Note: explicit `retry` on individual queries overrides this default.
+2. **Always use `waitFor`** — Query state updates are async. Never assert synchronously after `renderHook`.
+3. **Isolate QueryClient per test** — Create a new `QueryClient` for each test to prevent cross-test contamination. Do not share a client across tests.
+4. **Jest "did not exit" warning** — If you get this, set `gcTime: Infinity` on the test QueryClient to prevent garbage collection timers from hanging:
+   ```tsx
+   new QueryClient({
+     defaultOptions: {
+       queries: { retry: false, gcTime: Infinity },
+     },
+   })
+   ```
+5. **Component testing** — For testing components (not just hooks), render the component inside the wrapper:
+   ```tsx
+   import { render, screen, waitFor } from '@testing-library/react'
+   test('renders todo list', async () => {
+     render(<TodoList />, { wrapper: createWrapper() })
+     await waitFor(() => expect(screen.getByText('Test Todo')).toBeInTheDocument())
+   })
+   ```

package/skills/task/SKILL.md CHANGED Viewed

@@ -108,8 +108,7 @@ Match skills to the sub-area identified in domain_areas:
 **Cross-cutting** → combine skills from each sub-area involved.
 </skill_map>
-In SINGLE-ROLE mode: call each skill yourself before starting phase 4.
-In MULTI-ROLE mode: include explicit Skill() call instructions in each subagent prompt (see references/agent-dispatch.md).
+In ALL execution modes: include explicit Skill() call instructions in each subagent prompt (see references/agent-dispatch.md). The orchestrator does not need to load skills itself — agents load them before writing code.
 </required_skills>
 <available_mcps>
@@ -235,24 +234,28 @@ Constraints:
 <execution_mode_decision>
 At the end of phase 2, make an explicit execution mode decision and state it to the user:
-> **EXECUTION MODE: SINGLE-ROLE** — I will implement all changes directly.
+> **EXECUTION MODE: SINGLE-ROLE** — Single domain. I will dispatch 1-2 focused agents for implementation.
 OR
-> **EXECUTION MODE: MULTI-ROLE** — I will act as orchestrator, dispatching specialized agents via the Task tool.
+> **EXECUTION MODE: MULTI-ROLE** — Multiple domains. I will dispatch specialized agents across domains via the Task tool.
 OR
 > **EXECUTION MODE: PLAN** — The task is highly complex. I will enter plan mode to design a structured implementation plan before executing.
+**CRITICAL: In ALL execution modes, the orchestrator (main session) NEVER writes application code directly.** All implementation — components, hooks, pages, routes, services, tests — is delegated to agents via the Task tool. The orchestrator's role is: context gathering, agent dispatch, output review, integration glue (under 15 lines), and quality gates.
+The difference between SINGLE-ROLE and MULTI-ROLE is decomposition complexity, NOT whether agents are used:
+- **SINGLE-ROLE**: simpler decomposition (1-2 agents, same domain). Use when the task is contained within one package or domain.
+- **MULTI-ROLE**: complex decomposition (3+ agents, multiple domains). Use when the task spans packages or skill sets.
 Use PLAN mode when:
 - The task has 4+ distinct roles or implementation phases.
 - The scope is large enough that context window management becomes a concern.
 - The task benefits from upfront architectural planning before any code is written.
-In PLAN mode: use EnterPlanMode to design the full plan. Once the user approves it, exit plan mode and execute phases sequentially as MULTI-ROLE orchestrator, with context cleanup between major phases when needed.
-Follow this decision in phase 4. In MULTI-ROLE and PLAN modes, delegate application code to agents — your job is dispatch, review, integration, and quality gates.
+In PLAN mode: use EnterPlanMode to design the full plan. Once the user approves it, exit plan mode and execute phases sequentially as orchestrator, with context cleanup between major phases when needed.
 </execution_mode_decision>
 </phase_2b_multi_role_decomposition>
@@ -290,64 +293,62 @@ Follow this decision in phase 4. In MULTI-ROLE and PLAN modes, delegate applicat
 </phase_3_task_analysis>
 <phase_3b_baseline_capture>
-Run the verification plan before writing any code to establish the baseline for comparison.
+**MANDATORY.** Run the verification plan before writing any code to establish the baseline for comparison. Do NOT skip this phase.
+**Step 1: Standard quality gates** — run and record results (pass/fail, counts, bundle sizes).
-1. Run standard quality gates and record results (pass/fail, counts, bundle sizes).
-2. Run domain-specific checks from the verification plan:
-   - **Frontend**: if playwright/chrome-devtools MCPs are available, navigate to affected pages, capture screenshots, and measure performance (LCP, load time). Otherwise, record build output and bundle sizes.
-   - **Backend**: execute requests to affected endpoints (via curl or available API MCPs) and record response status, payload shape, and timing.
-   - **Database**: record current schema state for affected tables.
-3. Store all baseline values — these are compared against post-change results in phase 5b.
+**Step 2: MCP-based checks** — follow this decision tree in order:
-If testing MCPs are not available, skip those checks and note it:
-> **Baseline captured.** MCP-based visual/performance checks skipped — no browser MCPs available.
+1. Use ToolSearch to confirm which browser MCPs are available (playwright, chrome-devtools, or neither).
+2. **If browser MCPs are available AND the task touches frontend pages:**
+   a. Check if the dev server is running (attempt to navigate to `localhost` or the configured URL).
+   b. **If dev server is accessible:** navigate to each affected page, capture screenshots of key states, and measure performance (LCP, load time). Use Chrome DevTools traces or Playwright screenshots as appropriate.
+   c. **If dev server is NOT accessible:** ask the user whether to start it or skip visual checks. Do NOT silently skip — the user must confirm.
+3. **If no browser MCPs are available:** note it explicitly and proceed with shell-only checks (build output, bundle sizes).
+4. **Backend tasks:** execute requests to affected endpoints (via curl or available API MCPs) and record response status, payload shape, and timing.
+5. **Database tasks:** record current schema state for affected tables.
-In MULTI-ROLE mode, the orchestrator runs baseline capture before dispatching any agents.
+**Step 3: Store baseline** — all values captured here are compared against post-change results in phase 5b.
+When visual/performance checks are skipped, state the reason:
+> **Baseline captured.** MCP-based visual checks skipped — [reason: no browser MCPs available | dev server not running (user confirmed skip) | no frontend pages affected].
+The orchestrator ALWAYS runs baseline capture before dispatching any agents, regardless of execution mode.
 </phase_3b_baseline_capture>
 <phase_4_execution>
-Before writing any code, check the execution mode decision from phase 2.
+**CRITICAL: The orchestrator (main session) NEVER writes application code.** All implementation is dispatched to agents via the Task tool. The orchestrator may only write trivial glue (under 15 lines total): barrel file exports, small wiring imports, or config one-liners.
-**MULTI-ROLE → Follow <multi_role_orchestration> below.**
-**SINGLE-ROLE → Follow <single_role_implementation> below.**
+Before dispatching, check the execution mode decision from phase 2 to determine decomposition complexity.
-<multi_role_orchestration>
-As orchestrator, dispatch agents, review their output, and verify integration. Do not implement application code yourself.
+<agent_dispatch_protocol>
+This protocol applies to ALL execution modes (SINGLE-ROLE, MULTI-ROLE, and PLAN).
-You may write code directly only for trivial glue (under 15 lines total):
-- Adding an export line to a barrel file
-- Adding a small schema to the shared package that multiple agents need
-- Wiring an import in a top-level file after agents complete
+As orchestrator, your responsibilities are: context gathering, agent dispatch, output review, integration glue, and quality gates. You do NOT write application code (components, hooks, pages, routes, services, tests).
-Everything else should be delegated to an agent. For the agent prompt template and dispatch details, see references/agent-dispatch.md.
-Dispatch steps:
-1. Create TaskCreate entries for each role.
+**Dispatch steps:**
+1. Create TaskCreate entries for each role to track progress.
 2. For each role, dispatch a specialized agent via the Task tool with a self-contained prompt. Set the `model` parameter according to rule_4_model_selection.
 3. Launch independent agents in parallel. Launch dependent agents sequentially.
 4. Each agent runs its own quality gates before reporting completion. Review the agent's output and gate results before dispatching dependents.
 5. After all agents complete, proceed to phase 5 for the final cross-package quality gates.
-If you find yourself creating application files (routes, components, services, hooks, tests) while in MULTI-ROLE mode, delegate to an agent instead.
-</multi_role_orchestration>
+For the agent prompt template and dispatch details, see references/agent-dispatch.md.
-<single_role_implementation>
-Think through each step before acting. Share your reasoning at key decision points.
+**Self-check:** If you find yourself creating application files (routes, components, services, hooks, tests, pages), STOP and delegate to an agent instead.
+</agent_dispatch_protocol>
 <build_order>
-Work from micro to macro — build dependencies before dependents:
-1. Shared code first — new constants, types, schemas, or enums needed by multiple packages go in the shared/common package (discover its location from the project structure).
+Instruct agents to work from micro to macro — build dependencies before dependents:
+1. Shared code first — new constants, types, schemas, or enums needed by multiple packages go in the shared/common package.
 2. Check for reuse — before creating a helper, hook, component, or utility, search the codebase for existing code that can be used or extended.
 3. Implement the core change — build the feature/fix in the target package.
 4. Wire it together — connect the pieces across packages if needed.
-Decision tree:
+Decision tree (include in agent prompts when relevant):
 - Is this code used by multiple modules? YES → Create in the shared/common package.
 - Is this code used by multiple modules? NO → Is this component multi-file? YES → Create folder with index.tsx + related files. NO → Single file, co-located with usage.
 </build_order>
-If you created any temporary files or scripts for iteration, remove them at the end.
-</single_role_implementation>
 </phase_4_execution>
 <phase_5_quality_gates>