@codihaus/claude-skills 1.0.0 → 1.2.0

package/knowledge/stacks/nextjs/_index.md

@@ -0,0 +1,654 @@
+# Next.js
+
+> React meta-framework with SSR, App Router, and Server Components
+
+## Overview
+
+**What it is:**
+- Full-stack React framework
+- Server-side rendering (SSR) and static generation (SSG)
+- App Router with file-based routing (app/)
+- React Server Components by default
+- API routes and Server Actions
+- Built-in image optimization
+
+**When to use:**
+- React applications needing SEO (SSR)
+- Full-stack apps (frontend + API)
+- Projects wanting convention over configuration
+- Teams familiar with React ecosystem
+
+**Key concepts:**
+- **App Router** = File-based routes in `app/`
+- **Server Components** = Default, run on server
+- **Client Components** = Use `"use client"` directive
+- **Server Actions** = Form handling with `"use server"`
+- **Route Handlers** = API endpoints in `app/api/`
+- **Middleware** = Edge functions for request interception
+- **Layouts** = Shared UI in `layout.tsx`
+
+## Best Practices
+
+### Project Structure
+
+```
+nextjs-app/
+├── app/                      # App Router (Next.js 13+)
+│   ├── (auth)/               # Route groups (no URL impact)
+│   │   ├── login/
+│   │   └── register/
+│   ├── api/                  # API routes
+│   │   └── [route]/route.ts
+│   ├── dashboard/
+│   │   ├── page.tsx
+│   │   └── layout.tsx
+│   ├── layout.tsx            # Root layout
+│   ├── page.tsx              # Home page
+│   └── globals.css
+├── components/               # React components
+│   ├── ui/                   # UI primitives
+│   ├── forms/                # Form components
+│   └── common/               # Shared components
+├── lib/                      # Utilities and configs
+│   ├── actions/              # Server Actions
+│   ├── api.ts                # API client
+│   ├── auth.ts               # Auth utilities
+│   └── utils.ts              # Helpers
+├── hooks/                    # Custom React hooks
+├── types/                    # TypeScript types
+├── public/                   # Static assets
+└── middleware.ts             # Edge middleware
+```
+
+### Data Fetching
+
+```
+DO:
+✓ Fetch in Server Components by default (no useEffect)
+✓ Use async/await directly in components
+✓ Use Server Actions for mutations
+✓ Use fetch with caching options for external APIs
+✓ Use React cache() for request deduplication
+
+DON'T:
+✗ Use useEffect for initial data in Server Components
+✗ Forget revalidation strategy (stale data)
+✗ Mix Server and Client data fetching unnecessarily
+✗ Ignore loading.tsx and error.tsx
+```
+
+### Server vs Client Components
+
+```
+Server Components (default):
+✓ Data fetching
+✓ Accessing backend resources
+✓ Sensitive logic (API keys, tokens)
+✓ Large dependencies
+
+Client Components ("use client"):
+✓ Interactivity (onClick, onChange)
+✓ State (useState, useReducer)
+✓ Effects (useEffect)
+✓ Browser APIs (localStorage, etc.)
+✓ Custom hooks with state
+```
+
+### Server Actions
+
+```
+DO:
+✓ Define with "use server" directive
+✓ Use for form submissions and mutations
+✓ Validate input with Zod
+✓ Return typed responses
+✓ Use revalidatePath/revalidateTag after mutations
+
+DON'T:
+✗ Use for read operations (use Server Components)
+✗ Expose sensitive data in return values
+✗ Skip input validation
+✗ Forget error handling
+```
+
+### API Routes (Route Handlers)
+
+```
+DO:
+✓ Use app/api/ for REST endpoints
+✓ Export named functions (GET, POST, PUT, DELETE)
+✓ Use NextRequest/NextResponse
+✓ Validate request body
+✓ Return proper status codes
+
+DON'T:
+✗ Use for data consumed by own app (use Server Components)
+✗ Skip authentication checks
+✗ Return sensitive data without authorization
+```
+
+### State Management
+
+```
+DO:
+✓ Lift state up for shared client state
+✓ Use React Context for global client state
+✓ Use Server Components to avoid client state when possible
+✓ Use URL state (searchParams) for shareable state
+✓ Consider Zustand for complex client state
+
+DON'T:
+✗ Use Redux by default (often overkill with Server Components)
+✗ Store server data in client state (refetch instead)
+✗ Forget URL state for filters/pagination
+```
+
+## Anti-Patterns
+
+| Anti-Pattern | Problem | Better Approach |
+|--------------|---------|-----------------|
+| useEffect for data | Waterfalls, spinners | Fetch in Server Component |
+| "use client" everywhere | Loses RSC benefits | Only where needed |
+| Huge Client Components | Large bundle | Split server/client |
+| Fetching in layout.tsx | Blocks nested routes | Fetch in page.tsx or parallel |
+| No loading.tsx | No loading UI | Add loading.tsx per route |
+| Ignoring cache | Redundant fetches | Use fetch cache options |
+| API routes for own data | Extra roundtrip | Server Components/Actions |
+
+## For /dev-specs
+
+### Page Specification
+
+```markdown
+## Page: /products/[id]
+
+### Route
+- Path: `/products/:id`
+- File: `app/products/[id]/page.tsx`
+- Layout: Uses `app/products/layout.tsx`
+
+### Data Requirements
+- Product details (Server Component fetch)
+- Related products (parallel fetch)
+
+### Components
+| Component | Type | Purpose |
+|-----------|------|---------|
+| ProductGallery | Client | Image carousel with interactions |
+| ProductInfo | Server | Static product details |
+| AddToCart | Client | Cart interaction with state |
+
+### Loading State
+- `loading.tsx` with product skeleton
+
+### SEO
+- generateMetadata for dynamic title/description
+- Open Graph images
+```
+
+### Server Action Specification
+
+```markdown
+## Action: addToCart
+
+### Purpose
+Add product to user's cart
+
+### File
+`lib/actions/cart.ts`
+
+### Input
+```typescript
+{
+  productId: string,
+  quantity: number,
+  variant?: string,
+}
+```
+
+### Validation
+- Zod schema for input
+- Check product exists
+- Check stock availability
+
+### Side Effects
+- Update cart in database
+- revalidatePath('/cart')
+
+### Returns
+```typescript
+{ success: true, cartId: string }
+| { success: false, error: string }
+```
+```
+
+### API Route Specification
+
+```markdown
+## API: POST /api/webhooks/stripe
+
+### Purpose
+Handle Stripe webhook events
+
+### File
+`app/api/webhooks/stripe/route.ts`
+
+### Authentication
+- Verify Stripe signature
+- No user auth (webhook)
+
+### Events Handled
+| Event | Action |
+|-------|--------|
+| checkout.session.completed | Create order |
+| payment_intent.failed | Update order status |
+
+### Response
+- 200: Event processed
+- 400: Invalid payload
+- 401: Invalid signature
+```
+
+## For /dev-coding
+
+### Server Component with Data Fetching
+
+```typescript
+// app/products/[id]/page.tsx
+import { notFound } from 'next/navigation';
+import { getProduct, getRelatedProducts } from '@/lib/api';
+
+interface Props {
+  params: Promise<{ id: string }>;
+}
+
+export async function generateMetadata({ params }: Props) {
+  const { id } = await params;
+  const product = await getProduct(id);
+
+  if (!product) return { title: 'Not Found' };
+
+  return {
+    title: product.name,
+    description: product.description,
+    openGraph: {
+      images: [product.image],
+    },
+  };
+}
+
+export default async function ProductPage({ params }: Props) {
+  const { id } = await params;
+
+  // Parallel fetching
+  const [product, related] = await Promise.all([
+    getProduct(id),
+    getRelatedProducts(id),
+  ]);
+
+  if (!product) notFound();
+
+  return (
+    <div>
+      <h1>{product.name}</h1>
+      <p>{product.price}</p>
+      <AddToCartButton productId={id} />
+      <RelatedProducts products={related} />
+    </div>
+  );
+}
+```
+
+### Client Component
+
+```typescript
+// components/AddToCartButton.tsx
+"use client";
+
+import { useState, useTransition } from 'react';
+import { addToCart } from '@/lib/actions/cart';
+
+interface Props {
+  productId: string;
+}
+
+export function AddToCartButton({ productId }: Props) {
+  const [isPending, startTransition] = useTransition();
+  const [error, setError] = useState<string | null>(null);
+
+  const handleClick = () => {
+    setError(null);
+    startTransition(async () => {
+      const result = await addToCart({ productId, quantity: 1 });
+      if (!result.success) {
+        setError(result.error);
+      }
+    });
+  };
+
+  return (
+    <>
+      <button onClick={handleClick} disabled={isPending}>
+        {isPending ? 'Adding...' : 'Add to Cart'}
+      </button>
+      {error && <p className="text-red-500">{error}</p>}
+    </>
+  );
+}
+```
+
+### Server Action
+
+```typescript
+// lib/actions/cart.ts
+"use server";
+
+import { z } from 'zod';
+import { revalidatePath } from 'next/cache';
+import { auth } from '@/lib/auth';
+import { db } from '@/lib/db';
+
+const addToCartSchema = z.object({
+  productId: z.string().min(1),
+  quantity: z.number().int().positive(),
+});
+
+type AddToCartInput = z.infer<typeof addToCartSchema>;
+type AddToCartResult =
+  | { success: true; cartId: string }
+  | { success: false; error: string };
+
+export async function addToCart(input: AddToCartInput): Promise<AddToCartResult> {
+  // Validate input
+  const parsed = addToCartSchema.safeParse(input);
+  if (!parsed.success) {
+    return { success: false, error: 'Invalid input' };
+  }
+
+  // Check auth
+  const session = await auth();
+  if (!session?.user) {
+    return { success: false, error: 'Please sign in' };
+  }
+
+  try {
+    // Add to cart
+    const cart = await db.cart.upsert({
+      where: { userId: session.user.id },
+      create: {
+        userId: session.user.id,
+        items: { create: parsed.data },
+      },
+      update: {
+        items: { create: parsed.data },
+      },
+    });
+
+    revalidatePath('/cart');
+    return { success: true, cartId: cart.id };
+  } catch (error) {
+    return { success: false, error: 'Failed to add to cart' };
+  }
+}
+```
+
+### API Route Handler
+
+```typescript
+// app/api/products/route.ts
+import { NextRequest, NextResponse } from 'next/server';
+import { z } from 'zod';
+import { auth } from '@/lib/auth';
+import { db } from '@/lib/db';
+
+const createProductSchema = z.object({
+  name: z.string().min(1),
+  price: z.number().positive(),
+  description: z.string().optional(),
+});
+
+export async function GET(request: NextRequest) {
+  const searchParams = request.nextUrl.searchParams;
+  const limit = parseInt(searchParams.get('limit') || '10');
+  const offset = parseInt(searchParams.get('offset') || '0');
+
+  const products = await db.product.findMany({
+    take: limit,
+    skip: offset,
+    orderBy: { createdAt: 'desc' },
+  });
+
+  return NextResponse.json({ data: products });
+}
+
+export async function POST(request: NextRequest) {
+  // Check auth
+  const session = await auth();
+  if (!session?.user?.isAdmin) {
+    return NextResponse.json(
+      { error: 'Unauthorized' },
+      { status: 401 }
+    );
+  }
+
+  // Validate body
+  const body = await request.json();
+  const parsed = createProductSchema.safeParse(body);
+
+  if (!parsed.success) {
+    return NextResponse.json(
+      { error: 'Invalid input', details: parsed.error.flatten() },
+      { status: 400 }
+    );
+  }
+
+  // Create product
+  const product = await db.product.create({
+    data: parsed.data,
+  });
+
+  return NextResponse.json({ data: product }, { status: 201 });
+}
+```
+
+### Middleware (Auth)
+
+```typescript
+// middleware.ts
+import { NextResponse } from 'next/server';
+import type { NextRequest } from 'next/server';
+import { auth } from '@/lib/auth';
+
+export async function middleware(request: NextRequest) {
+  const session = await auth();
+
+  // Protect dashboard routes
+  if (request.nextUrl.pathname.startsWith('/dashboard')) {
+    if (!session) {
+      return NextResponse.redirect(new URL('/login', request.url));
+    }
+  }
+
+  // Protect admin routes
+  if (request.nextUrl.pathname.startsWith('/admin')) {
+    if (!session?.user?.isAdmin) {
+      return NextResponse.redirect(new URL('/unauthorized', request.url));
+    }
+  }
+
+  return NextResponse.next();
+}
+
+export const config = {
+  matcher: ['/dashboard/:path*', '/admin/:path*'],
+};
+```
+
+### Loading and Error States
+
+```typescript
+// app/products/[id]/loading.tsx
+export default function Loading() {
+  return (
+    <div className="animate-pulse">
+      <div className="h-8 bg-gray-200 rounded w-1/4 mb-4" />
+      <div className="h-4 bg-gray-200 rounded w-1/2 mb-2" />
+      <div className="h-64 bg-gray-200 rounded" />
+    </div>
+  );
+}
+
+// app/products/[id]/error.tsx
+"use client";
+
+interface Props {
+  error: Error & { digest?: string };
+  reset: () => void;
+}
+
+export default function Error({ error, reset }: Props) {
+  return (
+    <div className="text-center py-10">
+      <h2>Something went wrong!</h2>
+      <p className="text-gray-500">{error.message}</p>
+      <button onClick={reset} className="mt-4 btn">
+        Try again
+      </button>
+    </div>
+  );
+}
+```
+
+## For /dev-review
+
+### Server Component Checklist
+
+- [ ] Data fetching in Server Components (not useEffect)
+- [ ] Parallel fetching with Promise.all
+- [ ] Proper loading.tsx for each route segment
+- [ ] error.tsx for error boundaries
+- [ ] not-found.tsx for 404 handling
+- [ ] generateMetadata for SEO
+
+### Client Component Checklist
+
+- [ ] "use client" only where needed
+- [ ] Minimal bundle size (no large deps)
+- [ ] useTransition for non-blocking updates
+- [ ] Proper error handling in actions
+- [ ] Loading states during transitions
+
+### Security Checklist
+
+- [ ] Server Actions validate input
+- [ ] API routes check authorization
+- [ ] Middleware protects routes
+- [ ] No secrets exposed to client
+- [ ] CSRF protection on mutations
+- [ ] Rate limiting on API routes
+
+### Performance Checklist
+
+- [ ] Images use next/image
+- [ ] Dynamic imports for heavy components
+- [ ] Route segments have loading.tsx
+- [ ] Proper cache headers on fetch
+- [ ] Static generation where possible
+
+### Common Mistakes
+
+| Mistake | Impact | Fix |
+|---------|--------|-----|
+| useEffect for data | Waterfalls | Server Component fetch |
+| "use client" on page | Loses SSR | Keep pages as Server Components |
+| No loading.tsx | No loading UI | Add per route segment |
+| Fetching in layout | Blocks children | Fetch in page or parallel |
+| Large Client Components | Big bundle | Split and lazy load |
+| No error boundary | Crashes page | Add error.tsx |
+
+## Integration
+
+### With Directus
+
+```typescript
+// lib/directus.ts
+import { createDirectus, rest, authentication } from '@directus/sdk';
+
+const directus = createDirectus<Schema>(process.env.DIRECTUS_URL!)
+  .with(rest())
+  .with(authentication());
+
+export default directus;
+
+// lib/api/products.ts
+import directus from '@/lib/directus';
+import { readItems, readItem } from '@directus/sdk';
+
+export async function getProducts() {
+  return directus.request(
+    readItems('products', {
+      filter: { status: { _eq: 'published' } },
+      sort: ['-date_created'],
+    })
+  );
+}
+
+export async function getProduct(id: string) {
+  return directus.request(readItem('products', id));
+}
+```
+
+### With NextAuth.js
+
+```typescript
+// lib/auth.ts
+import NextAuth from 'next-auth';
+import GitHub from 'next-auth/providers/github';
+
+export const { handlers, auth, signIn, signOut } = NextAuth({
+  providers: [GitHub],
+  callbacks: {
+    session({ session, token }) {
+      if (token.sub) session.user.id = token.sub;
+      return session;
+    },
+  },
+});
+
+// app/api/auth/[...nextauth]/route.ts
+import { handlers } from '@/lib/auth';
+export const { GET, POST } = handlers;
+```
+
+### With Prisma
+
+```typescript
+// lib/db.ts
+import { PrismaClient } from '@prisma/client';
+
+const globalForPrisma = globalThis as unknown as {
+  prisma: PrismaClient | undefined;
+};
+
+export const db = globalForPrisma.prisma ?? new PrismaClient();
+
+if (process.env.NODE_ENV !== 'production') {
+  globalForPrisma.prisma = db;
+}
+```
+
+## Resources
+
+### Official Docs
+- Docs: https://nextjs.org/docs
+- App Router: https://nextjs.org/docs/app
+- Learn: https://nextjs.org/learn
+
+### Context7 Queries
+
+```
+Query: "Next.js 15 App Router data fetching"
+Query: "Next.js Server Actions best practices"
+Query: "Next.js middleware authentication"
+Query: "Next.js Server Components patterns"
+```