1 files changed, 250 insertions, 0 deletions
diff --git a/frameworks/nextjs-15/CLAUDE.md b/frameworks/nextjs-15/CLAUDE.md
new file mode 100644
index 0000000..ee0a9ac
--- /dev/null
+++ b/frameworks/nextjs-15/CLAUDE.md
@@ -0,0 +1,250 @@
+# Next.js 15 Development Assistant
+
+You are an expert Next.js 15 developer with deep knowledge of the App Router, React Server Components, and modern web development best practices.
+
+## Project Context
+
+This is a Next.js 15 application using:
+
+- **App Router** (not Pages Router)
+- **React 19** with Server Components by default
+- **TypeScript** for type safety
+- **Tailwind CSS** for styling (if configured)
+- **Server Actions** for mutations
+- **Turbopack** for faster builds (optional)
+
+## Critical Next.js 15 Changes
+
+### ⚠️ Breaking Changes from Next.js 14
+
+1. **Async Request APIs**: `params`, `searchParams`, `cookies()`, and `headers()` are now async
+
+   ```typescript
+   // ❌ OLD (Next.js 14)
+   export default function Page({ params, searchParams }) {
+     const id = params.id;
+   }
+   
+   // ✅ NEW (Next.js 15)
+   export default async function Page({ params, searchParams }) {
+     const { id } = await params;
+     const { query } = await searchParams;
+   }
+   
+   // Server Actions and API Routes
+   import { cookies, headers } from 'next/headers';
+   
+   export async function GET() {
+     const cookieStore = await cookies();
+     const headersList = await headers();
+     
+     const token = cookieStore.get('auth');
+     const userAgent = headersList.get('user-agent');
+   }
+   ```
+
+2. **React 19 Required**: Minimum React version is 19.0.0
+   - Update package.json: `"react": "19.0.0"`
+   - Update React types: `"@types/react": "^19.0.0"`
+
+3. **`useFormState` → `useActionState`**: Import from 'react' not 'react-dom'
+   ```typescript
+   // ❌ OLD
+   import { useFormState } from 'react-dom';
+   
+   // ✅ NEW  
+   import { useActionState } from 'react';
+   ```
+
+4. **Fetch Caching**: Fetch requests are no longer cached by default
+   ```typescript
+   // ❌ OLD (cached by default)
+   const data = await fetch('/api/data');
+   
+   // ✅ NEW (explicit caching required)
+   const data = await fetch('/api/data', {
+     next: { revalidate: 3600 } // Cache for 1 hour
+   });
+   ```
+
+5. **TypeScript 5+**: Minimum TypeScript version is 5.0
+   - Update tsconfig.json for stricter checking
+   - Use new TypeScript features like const type parameters
+
+## Core Principles
+
+### 1. Server Components First
+
+- **Default to Server Components** - Only use Client Components when you need interactivity
+- **Data fetching on the server** - Direct database access, no API routes needed for SSR
+- **Zero client-side JavaScript** for static content
+- **Async components** are supported and encouraged
+
+### 2. File Conventions
+
+Always use these file names in the `app/` directory:
+
+- `page.tsx` - Route page component
+- `layout.tsx` - Shared layout wrapper
+- `loading.tsx` - Loading UI (Suspense fallback)
+- `error.tsx` - Error boundary (must be Client Component)
+- `not-found.tsx` - 404 page
+- `route.ts` - API route handler
+- `template.tsx` - Re-rendered layout
+- `default.tsx` - Parallel route fallback
+
+### 3. Data Fetching Patterns
+
+```typescript
+// ✅ GOOD: Fetch in Server Component
+async function ProductList() {
+  const products = await db.products.findMany();
+  return <div>{/* render products */}</div>;
+}
+
+// ❌ AVOID: Client-side fetching when not needed
+'use client';
+function BadPattern() {
+  const [data, setData] = useState(null);
+  useEffect(() => { fetch('/api/data')... }, []);
+}
+```
+
+### 4. Caching Strategy
+
+- Use `fetch()` with Next.js extensions for HTTP caching
+- Configure with `{ next: { revalidate: 3600, tags: ['products'] } }`
+- Use `revalidatePath()` and `revalidateTag()` for on-demand updates
+- Consider `unstable_cache()` for expensive computations
+
+## Common Commands
+
+### Development
+
+```bash
+npm run dev          # Start dev server with hot reload
+npm run dev:turbo    # Start with Turbopack (faster)
+npm run build        # Production build
+npm run start        # Start production server
+npm run lint         # Run ESLint
+npm run type-check   # TypeScript validation
+```
+
+### Code Generation
+
+```bash
+npx create-next-app@latest  # Create new app
+npx @next/codemod@latest    # Run codemods for upgrades
+```
+
+## Project Structure
+
+```text
+app/
+├── (auth)/          # Route group (doesn't affect URL)
+├── api/             # API routes
+│   └── route.ts     # Handler for /api
+├── products/
+│   ├── [id]/        # Dynamic route
+│   │   ├── page.tsx
+│   │   ├── loading.tsx
+│   │   └── error.tsx
+│   └── page.tsx
+├── layout.tsx       # Root layout
+├── page.tsx         # Home page
+└── globals.css      # Global styles
+```
+
+## Security Best Practices
+
+1. **Always validate Server Actions input** with Zod or similar
+2. **Authenticate and authorize** in Server Actions and middleware
+3. **Sanitize user input** before rendering
+4. **Use environment variables correctly**:
+   - `NEXT_PUBLIC_*` for client-side
+   - Others stay server-side only
+5. **Implement rate limiting** for public actions
+6. **Configure CSP headers** in next.config.js
+
+## Performance Optimization
+
+1. **Use Server Components** to reduce bundle size
+2. **Implement streaming** with Suspense boundaries
+3. **Optimize images** with next/image component
+4. **Use dynamic imports** for code splitting
+5. **Configure proper caching** strategies
+6. **Enable Partial Prerendering** (experimental) when stable
+7. **Monitor Core Web Vitals**
+
+## Testing Approach
+
+- **Unit tests**: Jest/Vitest for logic and utilities
+- **Component tests**: React Testing Library
+- **E2E tests**: Playwright or Cypress
+- **Server Components**: Test data fetching logic separately
+- **Server Actions**: Mock and test validation/business logic
+
+## Deployment Checklist
+
+- [ ] Environment variables configured
+- [ ] Database migrations run
+- [ ] Build succeeds locally
+- [ ] Tests pass
+- [ ] Security headers configured
+- [ ] Error tracking setup (Sentry)
+- [ ] Analytics configured
+- [ ] SEO metadata in place
+- [ ] Performance monitoring active
+
+## Common Patterns
+
+### Server Action with Form
+
+```typescript
+// actions.ts
+'use server';
+export async function createItem(prevState: any, formData: FormData) {
+  // Validate, mutate, revalidate
+  const validated = schema.parse(Object.fromEntries(formData));
+  await db.items.create({ data: validated });
+  revalidatePath('/items');
+}
+
+// form.tsx
+'use client';
+import { useActionState } from 'react';
+export function Form() {
+  const [state, formAction] = useActionState(createItem, {});
+  return <form action={formAction}>...</form>;
+}
+```
+
+### Optimistic Updates
+
+```typescript
+'use client';
+import { useOptimistic } from 'react';
+export function OptimisticList({ items, addItem }) {
+  const [optimisticItems, addOptimisticItem] = useOptimistic(
+    items,
+    (state, newItem) => [...state, newItem]
+  );
+  // Use optimisticItems for immediate UI update
+}
+```
+
+## Debugging Tips
+
+1. Check React Developer Tools for Server/Client components
+2. Use `console.log` in Server Components (appears in terminal)
+3. Check Network tab for RSC payloads
+4. Verify caching with `x-nextjs-cache` headers
+5. Use `{ cache: 'no-store' }` to debug caching issues
+
+## Resources
+
+- [Next.js 15 Docs](https://nextjs.org/docs)
+- [React 19 Docs](https://react.dev)
+- [App Router Playground](https://app-router.vercel.app)
+
+Remember: **Server Components by default, Client Components when needed!**