@kood/claude-code 0.3.6 → 0.3.8

package/templates/nextjs/docs/library/nextjs/index.md

@@ -0,0 +1,291 @@
+# Next.js - Index
+
+> Next.js 15 App Router core concepts
+
+<context>
+@app-router.md
+@server-actions.md
+@route-handlers.md
+@middleware.md
+@caching.md
+</context>
+
+---
+
+## Core Concepts
+
+| Concept | Description |
+|---------|-------------|
+| **App Router** | File-based routing (`app/` directory) |
+| **Server Components** | Default components (server rendering) |
+| **Client Components** | Requires `"use client"` declaration |
+| **Server Actions** | `"use server"` functions (type-safe API) |
+| **Route Handlers** | REST API endpoints (`app/api/`) |
+
+---
+
+## Quick Start
+
+### Create Project
+
+```bash
+npx create-next-app@latest my-app --typescript --tailwind --app
+cd my-app
+npm run dev
+```
+
+### Basic Page
+
+```typescript
+// app/page.tsx (Server Component - default)
+export default async function HomePage() {
+  const data = await fetch('https://api.example.com/data')
+  const json = await data.json()
+
+  return <div>{json.title}</div>
+}
+```
+
+### Client Component
+
+```typescript
+// app/_components/counter.tsx
+"use client"
+
+import { useState } from "react"
+
+export function Counter() {
+  const [count, setCount] = useState(0)
+  return <button onClick={() => setCount(count + 1)}>{count}</button>
+}
+```
+
+---
+
+## File Structure
+
+```
+app/
+├── layout.tsx          # Root layout (required)
+├── page.tsx            # Home (/)
+├── about/
+│   └── page.tsx        # /about
+├── blog/
+│   ├── page.tsx        # /blog
+│   └── [slug]/
+│       └── page.tsx    # /blog/:slug
+└── api/
+    └── posts/
+        └── route.ts    # API /api/posts
+```
+
+---
+
+## Key Files
+
+| File | Purpose |
+|------|---------|
+| `layout.tsx` | Shared layout (nestable) |
+| `page.tsx` | Page component |
+| `loading.tsx` | Loading UI (Suspense) |
+| `error.tsx` | Error UI (Error Boundary) |
+| `not-found.tsx` | 404 page |
+| `route.ts` | API endpoint |
+
+---
+
+## Server vs Client Components
+
+| Aspect | Server | Client |
+|--------|--------|--------|
+| Declaration | Default | `"use client"` |
+| Data Fetching | ✅ async/await | ❌ (use useQuery) |
+| Hooks | ❌ | ✅ useState, useEffect |
+| Browser API | ❌ | ✅ window, localStorage |
+| Event Handlers | ❌ | ✅ onClick, onChange |
+
+**Rules:**
+- Server Components are default → add `"use client"` only when needed
+- Server Components can contain Client Components
+- Client Components cannot contain Server Components (but can receive them as props)
+
+---
+
+## Server Actions
+
+```typescript
+// app/actions.ts
+"use server"
+
+import { z } from "zod"
+import { revalidatePath } from "next/cache"
+
+const schema = z.object({
+  title: z.string().min(1),
+  content: z.string(),
+})
+
+export async function createPost(formData: FormData) {
+  const parsed = schema.parse({
+    title: formData.get("title"),
+    content: formData.get("content"),
+  })
+
+  const post = await prisma.post.create({ data: parsed })
+  revalidatePath("/posts")
+  return post
+}
+```
+
+---
+
+## Route Handlers
+
+```typescript
+// app/api/posts/route.ts
+import { NextRequest, NextResponse } from "next/server"
+
+export async function GET(request: NextRequest) {
+  const posts = await prisma.post.findMany()
+  return NextResponse.json(posts)
+}
+
+export async function POST(request: NextRequest) {
+  const body = await request.json()
+  const post = await prisma.post.create({ data: body })
+  return NextResponse.json(post, { status: 201 })
+}
+```
+
+---
+
+## Middleware
+
+```typescript
+// middleware.ts
+import { NextResponse } from "next/server"
+import type { NextRequest } from "next/server"
+
+export function middleware(request: NextRequest) {
+  const token = request.cookies.get("token")
+
+  if (!token) {
+    return NextResponse.redirect(new URL("/login", request.url))
+  }
+
+  return NextResponse.next()
+}
+
+export const config = {
+  matcher: ["/dashboard/:path*", "/profile/:path*"],
+}
+```
+
+---
+
+## Data Fetching
+
+### Server Component (recommended)
+
+```typescript
+export default async function PostsPage() {
+  const posts = await prisma.post.findMany() // Direct DB access
+  return <PostsList posts={posts} />
+}
+```
+
+### Client Component (TanStack Query)
+
+```typescript
+"use client"
+
+import { useQuery } from "@tanstack/react-query"
+
+export function PostsList() {
+  const { data } = useQuery({
+    queryKey: ["posts"],
+    queryFn: () => fetch("/api/posts").then(r => r.json()),
+  })
+
+  return <ul>{data?.map(post => <li key={post.id}>{post.title}</li>)}</ul>
+}
+```
+
+---
+
+## Caching
+
+| Function | Purpose |
+|----------|---------|
+| `revalidatePath("/posts")` | Invalidate specific path cache |
+| `revalidateTag("posts")` | Invalidate tag-based cache |
+| `unstable_cache()` | Cache function results |
+
+```typescript
+import { revalidatePath, revalidateTag } from "next/cache"
+
+export async function createPost(data: PostInput) {
+  const post = await prisma.post.create({ data })
+
+  revalidatePath("/posts") // Invalidate /posts cache
+  revalidateTag("posts")   // Invalidate "posts" tag cache
+
+  return post
+}
+```
+
+---
+
+## Environment Variables
+
+```bash
+# .env.local
+DATABASE_URL="postgresql://..."
+NEXTAUTH_SECRET="..."
+NEXTAUTH_URL="http://localhost:3000"
+NEXT_PUBLIC_API_URL="https://api.example.com"
+```
+
+**Rules:**
+- `NEXT_PUBLIC_*`: Accessible in client
+- Others: Server-only
+
+---
+
+## Deployment
+
+### Vercel (recommended)
+
+```bash
+npm i -g vercel
+vercel
+```
+
+### Docker
+
+```dockerfile
+FROM node:20-alpine
+WORKDIR /app
+COPY package*.json ./
+RUN npm ci
+COPY . .
+RUN npm run build
+CMD ["npm", "start"]
+```
+
+### Node.js
+
+```bash
+npm run build
+npm start
+```
+
+---
+
+## References
+
+- [App Router](app-router.md)
+- [Server Actions](server-actions.md)
+- [Route Handlers](route-handlers.md)
+- [Middleware](middleware.md)
+- [Caching](caching.md)

package/templates/nextjs/docs/library/nextjs/middleware.md

@@ -0,0 +1,391 @@
+# Middleware
+
+> Functions executed before request processing
+
+---
+
+## Basic Usage
+
+```typescript
+// middleware.ts (root)
+import { NextResponse } from "next/server"
+import type { NextRequest } from "next/server"
+
+export function middleware(request: NextRequest) {
+  // Execute logic...
+  return NextResponse.next()
+}
+
+// Matcher configuration
+export const config = {
+  matcher: ["/dashboard/:path*", "/api/:path*"],
+}
+```
+
+---
+
+## Response Types
+
+### NextResponse.next()
+
+```typescript
+// Pass request to next middleware or route
+export function middleware(request: NextRequest) {
+  return NextResponse.next()
+}
+```
+
+### NextResponse.redirect()
+
+```typescript
+// Redirect to different URL
+export function middleware(request: NextRequest) {
+  return NextResponse.redirect(new URL("/login", request.url))
+}
+```
+
+### NextResponse.rewrite()
+
+```typescript
+// Render different page while keeping URL
+export function middleware(request: NextRequest) {
+  return NextResponse.rewrite(new URL("/dashboard/home", request.url))
+}
+```
+
+---
+
+## Authentication
+
+```typescript
+import { NextResponse } from "next/server"
+import type { NextRequest } from "next/server"
+
+export function middleware(request: NextRequest) {
+  const token = request.cookies.get("token")
+
+  // Redirect to login if no token
+  if (!token) {
+    return NextResponse.redirect(new URL("/login", request.url))
+  }
+
+  return NextResponse.next()
+}
+
+export const config = {
+  matcher: ["/dashboard/:path*", "/profile/:path*"],
+}
+```
+
+---
+
+## Cookie Handling
+
+### Reading
+
+```typescript
+export function middleware(request: NextRequest) {
+  const token = request.cookies.get("token")
+  const userId = request.cookies.get("userId")
+
+  console.log({ token, userId })
+
+  return NextResponse.next()
+}
+```
+
+### Setting
+
+```typescript
+export function middleware(request: NextRequest) {
+  const response = NextResponse.next()
+
+  response.cookies.set("visited", "true", {
+    httpOnly: true,
+    secure: true,
+    maxAge: 60 * 60 * 24 * 7, // 7 days
+  })
+
+  return response
+}
+```
+
+---
+
+## Headers Handling
+
+### Reading
+
+```typescript
+export function middleware(request: NextRequest) {
+  const userAgent = request.headers.get("user-agent")
+  const authorization = request.headers.get("authorization")
+
+  console.log({ userAgent, authorization })
+
+  return NextResponse.next()
+}
+```
+
+### Setting
+
+```typescript
+export function middleware(request: NextRequest) {
+  const response = NextResponse.next()
+
+  response.headers.set("X-Custom-Header", "value")
+  response.headers.set("X-Request-Id", crypto.randomUUID())
+
+  return response
+}
+```
+
+---
+
+## Path-based Processing
+
+```typescript
+export function middleware(request: NextRequest) {
+  const { pathname } = request.nextUrl
+
+  // /api/* routes
+  if (pathname.startsWith("/api/")) {
+    const token = request.headers.get("authorization")
+
+    if (!token) {
+      return NextResponse.json({ error: "Unauthorized" }, { status: 401 })
+    }
+  }
+
+  // /admin/* routes
+  if (pathname.startsWith("/admin/")) {
+    const role = request.cookies.get("role")?.value
+
+    if (role !== "admin") {
+      return NextResponse.redirect(new URL("/", request.url))
+    }
+  }
+
+  return NextResponse.next()
+}
+```
+
+---
+
+## Matcher Configuration
+
+### Array
+
+```typescript
+export const config = {
+  matcher: ["/dashboard/:path*", "/profile/:path*"],
+}
+```
+
+### Regex
+
+```typescript
+export const config = {
+  matcher: [
+    /*
+     * Exclude paths:
+     * - _next/static (static files)
+     * - _next/image (image optimization)
+     * - favicon.ico (favicon)
+     */
+    "/((?!_next/static|_next/image|favicon.ico).*)",
+  ],
+}
+```
+
+### Conditional
+
+```typescript
+export const config = {
+  matcher: [
+    "/dashboard/:path*",
+    {
+      source: "/api/:path*",
+      has: [
+        { type: "header", key: "authorization" },
+      ],
+    },
+  ],
+}
+```
+
+---
+
+## Logging
+
+```typescript
+export function middleware(request: NextRequest) {
+  const start = Date.now()
+
+  const response = NextResponse.next()
+
+  const duration = Date.now() - start
+
+  console.log({
+    method: request.method,
+    url: request.url,
+    duration: `${duration}ms`,
+    status: response.status,
+  })
+
+  return response
+}
+```
+
+---
+
+## Rate Limiting
+
+```typescript
+import { NextResponse } from "next/server"
+import type { NextRequest } from "next/server"
+
+const rateLimit = new Map<string, { count: number; resetAt: number }>()
+
+const LIMIT = 10 // 10 requests
+const WINDOW = 60 * 1000 // 1 minute
+
+export function middleware(request: NextRequest) {
+  const ip = request.ip || "unknown"
+  const now = Date.now()
+
+  const record = rateLimit.get(ip)
+
+  if (!record || now > record.resetAt) {
+    rateLimit.set(ip, { count: 1, resetAt: now + WINDOW })
+    return NextResponse.next()
+  }
+
+  if (record.count >= LIMIT) {
+    return NextResponse.json(
+      { error: "Too many requests" },
+      { status: 429 }
+    )
+  }
+
+  record.count++
+  return NextResponse.next()
+}
+
+export const config = {
+  matcher: "/api/:path*",
+}
+```
+
+---
+
+## Geolocation
+
+```typescript
+export function middleware(request: NextRequest) {
+  const country = request.geo?.country || "US"
+  const city = request.geo?.city || "Unknown"
+
+  const response = NextResponse.next()
+  response.headers.set("X-Country", country)
+  response.headers.set("X-City", city)
+
+  return response
+}
+```
+
+---
+
+## A/B Testing
+
+```typescript
+import { NextResponse } from "next/server"
+import type { NextRequest } from "next/server"
+
+export function middleware(request: NextRequest) {
+  const bucket = request.cookies.get("bucket")
+
+  if (!bucket) {
+    const newBucket = Math.random() > 0.5 ? "A" : "B"
+    const response = NextResponse.next()
+
+    response.cookies.set("bucket", newBucket)
+
+    if (newBucket === "B") {
+      return NextResponse.rewrite(new URL("/variant-b", request.url))
+    }
+
+    return response
+  }
+
+  if (bucket.value === "B") {
+    return NextResponse.rewrite(new URL("/variant-b", request.url))
+  }
+
+  return NextResponse.next()
+}
+
+export const config = {
+  matcher: "/",
+}
+```
+
+---
+
+## Best Practices
+
+### ✅ DO
+
+```typescript
+// 1. Keep logic lightweight
+export function middleware(request: NextRequest) {
+  const token = request.cookies.get("token")
+
+  if (!token) {
+    return NextResponse.redirect(new URL("/login", request.url))
+  }
+
+  return NextResponse.next()
+}
+
+// 2. Configure matcher
+export const config = {
+  matcher: ["/dashboard/:path*"],
+}
+```
+
+### ❌ DON'T
+
+```typescript
+// 1. Heavy database queries
+export async function middleware(request: NextRequest) {
+  // ❌ No DB queries in middleware
+  const user = await prisma.user.findUnique({ where: { id: "..." } })
+  return NextResponse.next()
+}
+
+// 2. Processing all requests without matcher
+export function middleware(request: NextRequest) {
+  // ❌ Performance degradation
+  return NextResponse.next()
+}
+```
+
+---
+
+## Using with NextAuth.js
+
+```typescript
+// middleware.ts
+export { default } from "next-auth/middleware"
+
+export const config = {
+  matcher: ["/dashboard/:path*", "/profile/:path*"],
+}
+```
+
+---
+
+## References
+
+- [Next.js Middleware](https://nextjs.org/docs/app/building-your-application/routing/middleware)