@harness-engineering/cli 1.23.2 → 1.24.0

package/dist/agents/skills/claude-code/next-server-actions/SKILL.md

@@ -0,0 +1,97 @@
+# Next.js Server Actions
+
+> Mutate server-side data directly from components using async functions — no API route required
+
+## When to Use
+
+- Submitting forms that create, update, or delete data
+- Implementing progressive enhancement (forms that work without JavaScript)
+- Replacing simple API routes that only handle POST mutations
+- Executing server-side logic triggered by user interaction in a Server or Client Component
+- Managing pending state and validation errors for form submissions
+
+## Instructions
+
+1. Declare a Server Action by adding `'use server'` at the top of an async function or at the top of a module containing only server functions.
+2. Use Server Actions directly in `<form action={myAction}>` for progressive enhancement — the form works without JavaScript.
+3. Use `useFormStatus()` from `react-dom` inside a child component to access pending state during form submission.
+4. Use `useFormState()` (renamed to `useActionState()` in React 19) to capture the return value of a Server Action and display validation errors.
+5. Always validate inputs on the server — never trust client-supplied data even when using TypeScript.
+6. Return structured error objects from Server Actions rather than throwing — thrown errors reach the nearest error boundary.
+7. Call `revalidatePath()` or `revalidateTag()` after mutations to purge stale cached data.
+8. Use Server Actions in Client Components by importing them — the function reference is serialized as a server reference, not executed client-side.
+9. Never expose sensitive business logic in the action's return value — only return what the UI needs.
+
+```typescript
+// app/actions/create-post.ts
+'use server';
+import { z } from 'zod';
+import { revalidatePath } from 'next/cache';
+
+const schema = z.object({ title: z.string().min(1).max(200) });
+
+export async function createPost(prevState: unknown, formData: FormData) {
+  const parsed = schema.safeParse({ title: formData.get('title') });
+  if (!parsed.success) {
+    return { errors: parsed.error.flatten().fieldErrors };
+  }
+  await db.post.create({ data: { title: parsed.data.title } });
+  revalidatePath('/posts');
+  return { errors: null };
+}
+
+// app/posts/new/page.tsx
+'use client';
+import { useFormState, useFormStatus } from 'react-dom';
+import { createPost } from '@/app/actions/create-post';
+
+function SubmitButton() {
+  const { pending } = useFormStatus();
+  return <button disabled={pending}>{pending ? 'Saving...' : 'Save'}</button>;
+}
+
+export default function NewPostPage() {
+  const [state, action] = useFormState(createPost, null);
+  return (
+    <form action={action}>
+      <input name="title" />
+      {state?.errors?.title && <p>{state.errors.title}</p>}
+      <SubmitButton />
+    </form>
+  );
+}
+```
+
+## Details
+
+Server Actions compile to POST requests under the hood — Next.js generates a unique action ID and routes the request to the server function at runtime. This means they work in environments without JavaScript (progressive enhancement) and do not require a separate API endpoint.
+
+**Progressive enhancement:** When a `<form action={serverAction}>` is rendered, the native HTML form submission triggers the Server Action even if client-side JS has not loaded. Enhance the experience with `useFormStatus` only after hydration.
+
+**Revalidation:** After a mutation, the Data Cache and Full Route Cache entries for affected paths remain stale until explicitly invalidated. Call `revalidatePath('/path')` to purge by route or `revalidateTag('tag')` to purge by cache tag — both are imported from `next/cache`.
+
+**Error handling:** Throwing inside a Server Action propagates the error to the nearest React error boundary. For user-facing validation errors, return a structured error object from the action instead of throwing.
+
+**Security:** Server Actions are POST endpoints — they are subject to CSRF by nature (cookies are sent automatically by browsers). Next.js includes built-in CSRF protection via origin checking in Server Actions. Do not disable this protection.
+
+**React 19 rename:** `useFormState` is renamed to `useActionState` in React 19 and moved from `react-dom` to `react`. Both work in Next.js 14/15 — prefer `useActionState` in new code.
+
+## Source
+
+https://nextjs.org/docs/app/building-your-application/data-fetching/server-actions-and-mutations
+
+## Process
+
+1. Read the instructions and examples in this document.
+2. Apply the patterns to your implementation, adapting to your specific context.
+3. Verify your implementation against the details and edge cases listed above.
+
+## Harness Integration
+
+- **Type:** knowledge — this skill is a reference document, not a procedural workflow.
+- **No tools or state** — consumed as context by other skills and agents.
+
+## Success Criteria
+
+- The patterns described in this document are applied correctly in the implementation.
+- Edge cases and anti-patterns listed in this document are avoided.

package/dist/agents/skills/claude-code/next-server-actions/skill.yaml

@@ -0,0 +1,44 @@
+name: next-server-actions
+version: "1.0.0"
+description: Server Actions, form mutations, progressive enhancement, and useFormState
+cognitive_mode: advisory-guide
+type: knowledge
+tier: 3
+triggers:
+  - manual
+platforms:
+  - claude-code
+  - gemini-cli
+  - cursor
+  - codex
+tools: []
+paths:
+  - "next.config.*"
+  - "**/app/**/*.tsx"
+  - "**/app/**/*.ts"
+  - "**/pages/**/*.tsx"
+related_skills:
+  - next-server-components
+  - next-app-router
+  - next-error-boundaries
+  - next-auth-patterns
+  - ts-utility-types
+stack_signals:
+  - nextjs
+  - react
+  - typescript
+keywords:
+  - server-actions
+  - use-server
+  - useFormState
+  - useFormStatus
+  - mutations
+  - progressive-enhancement
+  - form
+metadata:
+  author: community
+  upstream: https://nextjs.org/docs/app/building-your-application/data-fetching/server-actions-and-mutations
+state:
+  persistent: false
+  files: []
+depends_on: []

package/dist/agents/skills/claude-code/next-server-components/SKILL.md

@@ -0,0 +1,82 @@
+# Next.js Server Components
+
+> Keep data fetching and heavy logic on the server; push interactivity to the client only where needed
+
+## When to Use
+
+- Fetching data that does not require browser APIs or user interaction
+- Accessing backend resources (databases, file system, internal APIs) directly in components
+- Reducing client-side JavaScript bundle size
+- Passing sensitive credentials (API keys, tokens) through server-only code paths
+- Deciding where to draw the `'use client'` boundary in a component tree
+
+## Instructions
+
+1. Every component in `app/` is a Server Component by default — no directive needed. Add `'use client'` only when the component uses hooks, browser APIs, or event handlers.
+2. Server Components can be `async` — `await` data directly inside the component body instead of using `useEffect`.
+3. Never import server-only modules (database clients, `fs`, secret env vars) into Client Components. Use the `server-only` package to enforce this at build time.
+4. Pass server-fetched data to Client Components as props — do not share state across the boundary directly.
+5. Place `'use client'` as close to the leaf as possible — this minimizes the client bundle.
+6. Client Components can import and render Server Components as children via the `children` prop (composition), but cannot import a Server Component module directly.
+7. Use `React.cache()` to deduplicate fetch calls across a request when multiple Server Components fetch the same data.
+8. Mark utility modules with `import 'server-only'` to prevent accidental client-side imports.
+
+```typescript
+// app/dashboard/page.tsx — Server Component (async, no directive)
+import { db } from '@/lib/db'; // server-only module — safe here
+import { MetricCard } from './metric-card'; // Client Component receives data as props
+
+export default async function DashboardPage() {
+  const metrics = await db.query.metrics.findMany();
+  return (
+    <div>
+      {metrics.map(m => <MetricCard key={m.id} metric={m} />)}
+    </div>
+  );
+}
+
+// app/dashboard/metric-card.tsx — Client Component
+'use client';
+import { useState } from 'react';
+
+export function MetricCard({ metric }: { metric: Metric }) {
+  const [expanded, setExpanded] = useState(false);
+  return <div onClick={() => setExpanded(e => !e)}>{metric.label}</div>;
+}
+```
+
+## Details
+
+React Server Components (RSC) render on the server and send HTML + a serialized component tree to the client. They never ship their module code to the browser, so they can safely import server-only dependencies.
+
+**The boundary model:** `'use client'` marks a module as the root of a client subtree. All modules imported by that module are also bundled for the client — the directive propagates downward through the import graph. This is why pushing the boundary toward leaves reduces bundle size.
+
+**Serialization constraints:** Props crossing the server→client boundary must be serializable (strings, numbers, plain objects, arrays). Functions, class instances, and Promises cannot be passed directly as props to Client Components (Promises can be passed to Suspense-aware Client Components via `use()`).
+
+**Common mistakes:**
+
+- Adding `'use client'` to a file that imports a database client — the database client ends up in the bundle
+- Fetching data in a Client Component with `useEffect` when a Server Component parent could fetch it directly
+- Importing a Client Component into a Server Component and then re-exporting it — this works fine; the Client Component is still bundled only once
+
+**Performance note:** Server Components reduce Time to First Byte (TTFB) for data-heavy pages because HTML arrives pre-rendered. Interactivity is hydrated progressively.
+
+## Source
+
+https://nextjs.org/docs/app/building-your-application/rendering/server-components
+
+## Process
+
+1. Read the instructions and examples in this document.
+2. Apply the patterns to your implementation, adapting to your specific context.
+3. Verify your implementation against the details and edge cases listed above.
+
+## Harness Integration
+
+- **Type:** knowledge — this skill is a reference document, not a procedural workflow.
+- **No tools or state** — consumed as context by other skills and agents.
+
+## Success Criteria
+
+- The patterns described in this document are applied correctly in the implementation.
+- Edge cases and anti-patterns listed in this document are avoided.

package/dist/agents/skills/claude-code/next-server-components/skill.yaml

@@ -0,0 +1,43 @@
+name: next-server-components
+version: '1.0.0'
+description: React Server Components in Next.js — client/server boundaries, composition, and data access
+cognitive_mode: advisory-guide
+type: knowledge
+tier: 3
+triggers:
+  - manual
+platforms:
+  - claude-code
+  - gemini-cli
+  - cursor
+  - codex
+tools: []
+paths:
+  - 'next.config.*'
+  - '**/app/**/*.tsx'
+  - '**/app/**/*.ts'
+  - '**/pages/**/*.tsx'
+related_skills:
+  - next-app-router
+  - next-server-actions
+  - next-data-fetching
+  - next-streaming-suspense
+  - react-hooks-pattern
+stack_signals:
+  - next
+  - nextjs
+  - react
+keywords:
+  - server-components
+  - rsc
+  - use-client
+  - client-boundary
+  - server-rendering
+  - data-access
+metadata:
+  author: vercel
+  upstream: 'community/next.js-docs/server-components'
+state:
+  persistent: false
+  files: []
+depends_on: []

package/dist/agents/skills/claude-code/next-static-generation/SKILL.md

@@ -0,0 +1,75 @@
+# Next.js Static Generation
+
+> Pre-render pages at build time or on a schedule using SSG, generateStaticParams, and ISR
+
+## When to Use
+
+- Pages whose content does not change per-request (marketing pages, blog posts, documentation)
+- Routes with a finite, known set of dynamic segments (e.g., `/posts/[slug]`)
+- High-traffic pages where serving from CDN cache is preferable to per-request rendering
+- Implementing Incremental Static Regeneration (ISR) to refresh content on a schedule
+- Reducing server compute costs by pre-rendering at build time
+
+## Instructions
+
+1. Make a page statically rendered by not using dynamic functions (`cookies()`, `headers()`, `searchParams`) and not setting `dynamic = 'force-dynamic'`.
+2. Export `generateStaticParams()` from a dynamic route's `page.tsx` to pre-render all known slugs at build time.
+3. Set `export const revalidate = 60` (seconds) at the page or layout level to enable ISR — the page re-generates in the background after the interval.
+4. Use `revalidatePath()` or `revalidateTag()` from a Server Action or route handler for on-demand ISR triggered by a CMS webhook.
+5. Pass `{ next: { tags: ['posts'] } }` to `fetch()` to attach cache tags for granular invalidation.
+6. Set `export const dynamicParams = false` to return 404 for slugs not returned by `generateStaticParams()`.
+7. Use `notFound()` inside `generateStaticParams()` return values — simply omit slugs you want to 404.
+
+```typescript
+// app/posts/[slug]/page.tsx
+import { notFound } from 'next/navigation';
+
+export const revalidate = 3600; // Re-generate every hour
+
+export async function generateStaticParams() {
+  const posts = await fetch('https://api.example.com/posts', {
+    next: { tags: ['posts'] },
+  }).then(r => r.json());
+  return posts.map((p: { slug: string }) => ({ slug: p.slug }));
+}
+
+export default async function PostPage({ params }: { params: { slug: string } }) {
+  const post = await fetch(`https://api.example.com/posts/${params.slug}`, {
+    next: { tags: [`post-${params.slug}`] },
+  }).then(r => r.json());
+  if (!post) notFound();
+  return <article>{post.content}</article>;
+}
+```
+
+## Details
+
+Next.js App Router has four rendering modes: static (default), dynamic, streaming, and ISR. Static generation produces HTML at build time and serves it from a CDN — zero server compute per request.
+
+**ISR mechanics:** When `revalidate` is set, Next.js uses a stale-while-revalidate strategy. The first request after the interval triggers a background regeneration; the stale page is served during regeneration. This means the interval is a minimum, not a guarantee — high-traffic pages regenerate quickly, low-traffic pages may take longer.
+
+**On-demand ISR:** Call `revalidatePath('/posts/my-slug')` or `revalidateTag('posts')` from a route handler secured with a secret token. Wire this to your CMS webhook to regenerate pages immediately on content updates.
+
+**generateStaticParams at build time:** Next.js calls `generateStaticParams` during `next build` and pre-renders every returned slug. If `dynamicParams` is `true` (default), slugs not pre-rendered are rendered on-demand and then cached. If `false`, they return 404.
+
+**fetch() caching:** In the App Router, `fetch()` is extended to accept `{ next: { revalidate, tags } }` options. This opts individual fetch calls into the Data Cache, separate from the HTTP cache. Server Components without any dynamic functions are cached by the Full Route Cache.
+
+## Source
+
+https://nextjs.org/docs/app/building-your-application/rendering/static-and-dynamic-rendering
+
+## Process
+
+1. Read the instructions and examples in this document.
+2. Apply the patterns to your implementation, adapting to your specific context.
+3. Verify your implementation against the details and edge cases listed above.
+
+## Harness Integration
+
+- **Type:** knowledge — this skill is a reference document, not a procedural workflow.
+- **No tools or state** — consumed as context by other skills and agents.
+
+## Success Criteria
+
+- The patterns described in this document are applied correctly in the implementation.
+- Edge cases and anti-patterns listed in this document are avoided.

package/dist/agents/skills/claude-code/next-static-generation/skill.yaml

@@ -0,0 +1,44 @@
+name: next-static-generation
+version: "1.0.0"
+description: SSG, generateStaticParams, ISR, and revalidate strategies
+cognitive_mode: advisory-guide
+type: knowledge
+tier: 3
+triggers:
+  - manual
+platforms:
+  - claude-code
+  - gemini-cli
+  - cursor
+  - codex
+tools: []
+paths:
+  - "next.config.*"
+  - "**/app/**/*.tsx"
+  - "**/app/**/*.ts"
+  - "**/pages/**/*.tsx"
+related_skills:
+  - next-caching-strategies
+  - next-data-fetching
+  - next-app-router
+  - next-deployment-optimization
+  - ts-utility-types
+stack_signals:
+  - nextjs
+  - react
+  - typescript
+keywords:
+  - SSG
+  - static-generation
+  - generateStaticParams
+  - ISR
+  - revalidate
+  - on-demand-revalidation
+  - static-paths
+metadata:
+  author: community
+  upstream: https://nextjs.org/docs/app/building-your-application/rendering/static-and-dynamic-rendering
+state:
+  persistent: false
+  files: []
+depends_on: []

package/dist/agents/skills/claude-code/next-streaming-suspense/SKILL.md

@@ -0,0 +1,86 @@
+# Next.js Streaming and Suspense
+
+> Stream server-rendered HTML progressively using Suspense boundaries and loading.tsx
+
+## When to Use
+
+- Pages with slow data fetches where showing a skeleton immediately improves perceived performance
+- Preventing a single slow component from blocking the entire page render
+- Implementing loading UI without client-side state management
+- Building shell-first UX (instant layout, streamed content)
+- Integrating with React 18 concurrent features and Suspense-aware libraries
+
+## Instructions
+
+1. Create `loading.tsx` alongside `page.tsx` in any route segment — Next.js wraps the page in a `<Suspense>` boundary automatically.
+2. Wrap individual slow components in `<Suspense fallback={<Skeleton />}>` for finer-grained streaming control.
+3. Start data fetches before `await` to allow parallel fetching — initiate promises, then await them after wrapping in Suspense.
+4. Use the `use()` hook in Client Components to unwrap a Promise passed as a prop, suspending until it resolves.
+5. Never `await` a fetch at the top of a layout that wraps a Suspense boundary — this negates streaming by blocking the boundary parent.
+6. Prioritize streaming for above-the-fold content — wrap below-the-fold slow sections in Suspense instead.
+7. Keep `loading.tsx` as a Server Component — it can import static UI without any JS shipped to the client.
+
+```typescript
+// app/dashboard/page.tsx — parallel fetch with streaming
+import { Suspense } from 'react';
+import { MetricsSkeleton, ActivitySkeleton } from '@/components/skeletons';
+import { Metrics } from './metrics';
+import { Activity } from './activity';
+
+export default function DashboardPage() {
+  // Initiate fetches in parallel — do NOT await here
+  const metricsPromise = fetchMetrics();
+  const activityPromise = fetchActivity();
+
+  return (
+    <div>
+      <Suspense fallback={<MetricsSkeleton />}>
+        <Metrics promise={metricsPromise} />
+      </Suspense>
+      <Suspense fallback={<ActivitySkeleton />}>
+        <Activity promise={activityPromise} />
+      </Suspense>
+    </div>
+  );
+}
+
+// app/dashboard/metrics.tsx — async Server Component
+async function Metrics({ promise }: { promise: Promise<Metric[]> }) {
+  const metrics = await promise; // suspends until resolved
+  return <MetricsList items={metrics} />;
+}
+```
+
+## Details
+
+Next.js implements streaming via HTTP chunked transfer encoding. The server sends the initial HTML shell immediately, then streams additional HTML chunks as Suspense boundaries resolve. The browser progressively renders each chunk without waiting for the full response.
+
+**Suspense boundary placement:** Each `<Suspense>` boundary is an independent streaming unit. Content outside boundaries renders synchronously. Deeply nested boundaries allow granular streaming — the outermost boundary controls the shell, inner boundaries control content slots.
+
+**loading.tsx convention:** Next.js automatically wraps `page.tsx` in a Suspense boundary when `loading.tsx` exists in the same directory. The `loading.tsx` file is the fallback. This is equivalent to `<Suspense fallback={<Loading />}><Page /></Suspense>`.
+
+**Parallel vs sequential data fetching:** Two `await`s in sequence cause a waterfall — each fetch waits for the previous. Starting both fetches before any `await` (or using `Promise.all`) enables parallelism. With Suspense, each async Server Component can independently suspend without blocking siblings.
+
+**Error handling with Suspense:** Pair each `<Suspense>` boundary with an `<ErrorBoundary>` (or co-locate `error.tsx`) to handle fetch failures gracefully within that stream segment.
+
+**Trade-offs:** Streaming increases TTFB perception because the shell arrives fast, but Time to Fully Loaded may be similar. Streaming works best when content has natural priority ordering (fast shell, slower content).
+
+## Source
+
+https://nextjs.org/docs/app/building-your-application/routing/loading-ui-and-streaming
+
+## Process
+
+1. Read the instructions and examples in this document.
+2. Apply the patterns to your implementation, adapting to your specific context.
+3. Verify your implementation against the details and edge cases listed above.
+
+## Harness Integration
+
+- **Type:** knowledge — this skill is a reference document, not a procedural workflow.
+- **No tools or state** — consumed as context by other skills and agents.
+
+## Success Criteria
+
+- The patterns described in this document are applied correctly in the implementation.
+- Edge cases and anti-patterns listed in this document are avoided.

package/dist/agents/skills/claude-code/next-streaming-suspense/skill.yaml

@@ -0,0 +1,43 @@
+name: next-streaming-suspense
+version: "1.0.0"
+description: Streaming SSR, Suspense boundaries, and loading.tsx conventions
+cognitive_mode: advisory-guide
+type: knowledge
+tier: 3
+triggers:
+  - manual
+platforms:
+  - claude-code
+  - gemini-cli
+  - cursor
+  - codex
+tools: []
+paths:
+  - "next.config.*"
+  - "**/app/**/*.tsx"
+  - "**/app/**/*.ts"
+related_skills:
+  - next-server-components
+  - next-data-fetching
+  - next-error-boundaries
+  - tanstack-suspense-mode
+  - react-hooks-pattern
+stack_signals:
+  - nextjs
+  - react
+  - typescript
+keywords:
+  - streaming
+  - suspense
+  - loading-ui
+  - loading.tsx
+  - HTTP-streaming
+  - skeleton
+  - deferred
+metadata:
+  author: community
+  upstream: https://nextjs.org/docs/app/building-your-application/routing/loading-ui-and-streaming
+state:
+  persistent: false
+  files: []
+depends_on: []

package/dist/agents/skills/claude-code/next-testing-patterns/SKILL.md

@@ -0,0 +1,104 @@
+# Next.js Testing Patterns
+
+> Test App Router components, Server Actions, and Route Handlers with Jest, Vitest, and MSW
+
+## When to Use
+
+- Writing unit tests for Server Components and Client Components in the App Router
+- Testing Server Actions with mocked database calls
+- Integration testing Route Handlers with simulated HTTP requests
+- Setting up Mock Service Worker (MSW) for fetch interception in tests
+- Configuring Jest or Vitest for Next.js with proper module resolution
+
+## Instructions
+
+1. Use `@testing-library/react` for rendering Client Components — import from `@testing-library/react` as usual.
+2. Test Server Components by calling them as plain async functions — they are just async functions that return JSX.
+3. Mock `next/navigation` (`useRouter`, `usePathname`, `useSearchParams`) with `jest.mock()` or `vi.mock()` — these hooks are not available in tests.
+4. Mock `next/headers` (`cookies`, `headers`) for Server Components that read request headers or cookies.
+5. Use MSW (`msw`) to intercept `fetch()` calls in integration tests — set up a server with `setupServer()` and start/stop per test suite.
+6. Test Route Handlers by constructing a `NextRequest` and calling the handler directly — no HTTP server needed.
+7. Test Server Actions by calling them directly as async functions and asserting the return value.
+8. Use `next-router-mock` as a drop-in `useRouter` mock that supports assertions on navigation calls.
+
+```typescript
+// __tests__/server-component.test.tsx — testing a Server Component
+import { render, screen } from '@testing-library/react';
+import { PostList } from '@/components/post-list'; // Server Component
+
+// Mock data access module
+vi.mock('@/lib/posts', () => ({
+  getPosts: vi.fn().mockResolvedValue([
+    { id: '1', title: 'Hello World', slug: 'hello-world' },
+  ]),
+}));
+
+test('renders post titles', async () => {
+  const component = await PostList(); // call as async function
+  render(component);
+  expect(screen.getByText('Hello World')).toBeInTheDocument();
+});
+
+// __tests__/client-component.test.tsx — Client Component with router mock
+import { render, screen, fireEvent } from '@testing-library/react';
+import { useRouter } from 'next/navigation';
+import { NavButton } from '@/components/nav-button';
+
+vi.mock('next/navigation', () => ({ useRouter: vi.fn() }));
+
+test('navigates on click', () => {
+  const push = vi.fn();
+  vi.mocked(useRouter).mockReturnValue({ push } as any);
+  render(<NavButton href="/dashboard">Go to Dashboard</NavButton>);
+  fireEvent.click(screen.getByText('Go to Dashboard'));
+  expect(push).toHaveBeenCalledWith('/dashboard');
+});
+
+// __tests__/route-handler.test.ts — Route Handler unit test
+import { GET } from '@/app/api/posts/route';
+import { NextRequest } from 'next/server';
+
+test('returns posts as JSON', async () => {
+  const request = new NextRequest('http://localhost/api/posts');
+  const response = await GET(request);
+  expect(response.status).toBe(200);
+  const data = await response.json();
+  expect(Array.isArray(data)).toBe(true);
+});
+```
+
+## Details
+
+Testing Next.js App Router applications requires different strategies for Server Components, Client Components, and server-side functions — they run in different environments.
+
+**Server Component testing:** Server Components are async functions — call them directly and render the result. The key is mocking their dependencies (database calls, fetch, `next/headers`) rather than trying to render them in a browser environment.
+
+**next/navigation mocking:** `useRouter`, `usePathname`, `useSearchParams`, and `redirect` are not available in the test environment. Always mock `next/navigation`. For complex navigation testing, use the `next-router-mock` package which provides a mock router with state tracking.
+
+**MSW integration:** MSW intercepts `fetch()` at the network layer — no need to mock `fetch` globally. Set up `server.listen()` in `beforeAll`, `server.resetHandlers()` in `afterEach`, and `server.close()` in `afterAll`. Use `server.use()` within a test to override handlers for specific scenarios.
+
+**Vitest vs Jest:** Vitest is faster and has native ESM support — preferred for new Next.js projects. Configure `vitest.config.ts` with `@vitejs/plugin-react` and alias `next/navigation` to a mock. Jest requires `next/jest` transform configuration for App Router compatibility.
+
+**`next/cache` in tests:** `revalidatePath` and `revalidateTag` throw errors in test environments. Mock `next/cache` module entirely: `vi.mock('next/cache', () => ({ revalidatePath: vi.fn(), revalidateTag: vi.fn() }))`.
+
+**E2E testing:** For full integration tests including navigation and streaming, use Playwright with `next dev` or `next start`. Playwright can test App Router features (streaming, client navigation) that JSDOM-based unit tests cannot.
+
+## Source
+
+https://nextjs.org/docs/app/building-your-application/testing
+
+## Process
+
+1. Read the instructions and examples in this document.
+2. Apply the patterns to your implementation, adapting to your specific context.
+3. Verify your implementation against the details and edge cases listed above.
+
+## Harness Integration
+
+- **Type:** knowledge — this skill is a reference document, not a procedural workflow.
+- **No tools or state** — consumed as context by other skills and agents.
+
+## Success Criteria
+
+- The patterns described in this document are applied correctly in the implementation.
+- Edge cases and anti-patterns listed in this document are avoided.

package/dist/agents/skills/claude-code/next-testing-patterns/skill.yaml

@@ -0,0 +1,46 @@
+name: next-testing-patterns
+version: "1.0.0"
+description: Component testing with App Router, mocking server components, and MSW integration
+cognitive_mode: advisory-guide
+type: knowledge
+tier: 3
+triggers:
+  - manual
+platforms:
+  - claude-code
+  - gemini-cli
+  - cursor
+  - codex
+tools: []
+paths:
+  - "next.config.*"
+  - "**/*.test.tsx"
+  - "**/*.spec.tsx"
+  - "**/*.test.ts"
+  - "**/jest.config.*"
+  - "**/vitest.config.*"
+related_skills:
+  - next-server-components
+  - next-route-handlers
+  - next-server-actions
+  - react-hooks-pattern
+stack_signals:
+  - nextjs
+  - react
+  - typescript
+keywords:
+  - testing
+  - jest
+  - vitest
+  - MSW
+  - mock-server
+  - server-components-testing
+  - render
+  - integration-test
+metadata:
+  author: community
+  upstream: https://nextjs.org/docs/app/building-your-application/testing
+state:
+  persistent: false
+  files: []
+depends_on: []