@olives/devos 2.1.0

package/.agents/skills/nextjs-app-router-patterns/references/details.md

@@ -0,0 +1,428 @@
+# nextjs-app-router-patterns — detailed patterns and worked examples
+
+## Patterns
+
+### Pattern 1: Server Components with Data Fetching
+
+```typescript
+// app/products/page.tsx
+import { Suspense } from 'react'
+import { ProductList, ProductListSkeleton } from '@/components/products'
+import { FilterSidebar } from '@/components/filters'
+
+interface SearchParams {
+  category?: string
+  sort?: 'price' | 'name' | 'date'
+  page?: string
+}
+
+export default async function ProductsPage({
+  searchParams,
+}: {
+  searchParams: Promise<SearchParams>
+}) {
+  const params = await searchParams
+
+  return (
+    <div className="flex gap-8">
+      <FilterSidebar />
+      <Suspense
+        key={JSON.stringify(params)}
+        fallback={<ProductListSkeleton />}
+      >
+        <ProductList
+          category={params.category}
+          sort={params.sort}
+          page={Number(params.page) || 1}
+        />
+      </Suspense>
+    </div>
+  )
+}
+
+// components/products/ProductList.tsx - Server Component
+async function getProducts(filters: ProductFilters) {
+  const res = await fetch(
+    `${process.env.API_URL}/products?${new URLSearchParams(filters)}`,
+    { next: { tags: ['products'] } }
+  )
+  if (!res.ok) throw new Error('Failed to fetch products')
+  return res.json()
+}
+
+export async function ProductList({ category, sort, page }: ProductFilters) {
+  const { products, totalPages } = await getProducts({ category, sort, page })
+
+  return (
+    <div>
+      <div className="grid grid-cols-3 gap-4">
+        {products.map((product) => (
+          <ProductCard key={product.id} product={product} />
+        ))}
+      </div>
+      <Pagination currentPage={page} totalPages={totalPages} />
+    </div>
+  )
+}
+```
+
+### Pattern 2: Client Components with 'use client'
+
+```typescript
+// components/products/AddToCartButton.tsx
+'use client'
+
+import { useState, useTransition } from 'react'
+import { addToCart } from '@/app/actions/cart'
+
+export function AddToCartButton({ productId }: { productId: string }) {
+  const [isPending, startTransition] = useTransition()
+  const [error, setError] = useState<string | null>(null)
+
+  const handleClick = () => {
+    setError(null)
+    startTransition(async () => {
+      const result = await addToCart(productId)
+      if (result.error) {
+        setError(result.error)
+      }
+    })
+  }
+
+  return (
+    <div>
+      <button
+        onClick={handleClick}
+        disabled={isPending}
+        className="btn-primary"
+      >
+        {isPending ? 'Adding...' : 'Add to Cart'}
+      </button>
+      {error && <p className="text-red-500 text-sm">{error}</p>}
+    </div>
+  )
+}
+```
+
+### Pattern 3: Server Actions
+
+```typescript
+// app/actions/cart.ts
+"use server";
+
+import { revalidateTag } from "next/cache";
+import { cookies } from "next/headers";
+import { redirect } from "next/navigation";
+
+export async function addToCart(productId: string) {
+  const cookieStore = await cookies();
+  const sessionId = cookieStore.get("session")?.value;
+
+  if (!sessionId) {
+    redirect("/login");
+  }
+
+  try {
+    await db.cart.upsert({
+      where: { sessionId_productId: { sessionId, productId } },
+      update: { quantity: { increment: 1 } },
+      create: { sessionId, productId, quantity: 1 },
+    });
+
+    revalidateTag("cart");
+    return { success: true };
+  } catch (error) {
+    return { error: "Failed to add item to cart" };
+  }
+}
+
+export async function checkout(formData: FormData) {
+  const address = formData.get("address") as string;
+  const payment = formData.get("payment") as string;
+
+  // Validate
+  if (!address || !payment) {
+    return { error: "Missing required fields" };
+  }
+
+  // Process order
+  const order = await processOrder({ address, payment });
+
+  // Redirect to confirmation
+  redirect(`/orders/${order.id}/confirmation`);
+}
+```
+
+### Pattern 4: Parallel Routes
+
+```typescript
+// app/dashboard/layout.tsx
+export default function DashboardLayout({
+  children,
+  analytics,
+  team,
+}: {
+  children: React.ReactNode
+  analytics: React.ReactNode
+  team: React.ReactNode
+}) {
+  return (
+    <div className="dashboard-grid">
+      <main>{children}</main>
+      <aside className="analytics-panel">{analytics}</aside>
+      <aside className="team-panel">{team}</aside>
+    </div>
+  )
+}
+
+// app/dashboard/@analytics/page.tsx
+export default async function AnalyticsSlot() {
+  const stats = await getAnalytics()
+  return <AnalyticsChart data={stats} />
+}
+
+// app/dashboard/@analytics/loading.tsx
+export default function AnalyticsLoading() {
+  return <ChartSkeleton />
+}
+
+// app/dashboard/@team/page.tsx
+export default async function TeamSlot() {
+  const members = await getTeamMembers()
+  return <TeamList members={members} />
+}
+```
+
+### Pattern 5: Intercepting Routes (Modal Pattern)
+
+```typescript
+// File structure for photo modal
+// app/
+// ├── @modal/
+// │   ├── (.)photos/[id]/page.tsx  # Intercept
+// │   └── default.tsx
+// ├── photos/
+// │   └── [id]/page.tsx            # Full page
+// └── layout.tsx
+
+// app/@modal/(.)photos/[id]/page.tsx
+import { Modal } from '@/components/Modal'
+import { PhotoDetail } from '@/components/PhotoDetail'
+
+export default async function PhotoModal({
+  params,
+}: {
+  params: Promise<{ id: string }>
+}) {
+  const { id } = await params
+  const photo = await getPhoto(id)
+
+  return (
+    <Modal>
+      <PhotoDetail photo={photo} />
+    </Modal>
+  )
+}
+
+// app/photos/[id]/page.tsx - Full page version
+export default async function PhotoPage({
+  params,
+}: {
+  params: Promise<{ id: string }>
+}) {
+  const { id } = await params
+  const photo = await getPhoto(id)
+
+  return (
+    <div className="photo-page">
+      <PhotoDetail photo={photo} />
+      <RelatedPhotos photoId={id} />
+    </div>
+  )
+}
+
+// app/layout.tsx
+export default function RootLayout({
+  children,
+  modal,
+}: {
+  children: React.ReactNode
+  modal: React.ReactNode
+}) {
+  return (
+    <html>
+      <body>
+        {children}
+        {modal}
+      </body>
+    </html>
+  )
+}
+```
+
+### Pattern 6: Streaming with Suspense
+
+```typescript
+// app/product/[id]/page.tsx
+import { Suspense } from 'react'
+
+export default async function ProductPage({
+  params,
+}: {
+  params: Promise<{ id: string }>
+}) {
+  const { id } = await params
+
+  // This data loads first (blocking)
+  const product = await getProduct(id)
+
+  return (
+    <div>
+      {/* Immediate render */}
+      <ProductHeader product={product} />
+
+      {/* Stream in reviews */}
+      <Suspense fallback={<ReviewsSkeleton />}>
+        <Reviews productId={id} />
+      </Suspense>
+
+      {/* Stream in recommendations */}
+      <Suspense fallback={<RecommendationsSkeleton />}>
+        <Recommendations productId={id} />
+      </Suspense>
+    </div>
+  )
+}
+
+// These components fetch their own data
+async function Reviews({ productId }: { productId: string }) {
+  const reviews = await getReviews(productId) // Slow API
+  return <ReviewList reviews={reviews} />
+}
+
+async function Recommendations({ productId }: { productId: string }) {
+  const products = await getRecommendations(productId) // ML-based, slow
+  return <ProductCarousel products={products} />
+}
+```
+
+### Pattern 7: Route Handlers (API Routes)
+
+```typescript
+// app/api/products/route.ts
+import { NextRequest, NextResponse } from "next/server";
+
+export async function GET(request: NextRequest) {
+  const searchParams = request.nextUrl.searchParams;
+  const category = searchParams.get("category");
+
+  const products = await db.product.findMany({
+    where: category ? { category } : undefined,
+    take: 20,
+  });
+
+  return NextResponse.json(products);
+}
+
+export async function POST(request: NextRequest) {
+  const body = await request.json();
+
+  const product = await db.product.create({
+    data: body,
+  });
+
+  return NextResponse.json(product, { status: 201 });
+}
+
+// app/api/products/[id]/route.ts
+export async function GET(
+  request: NextRequest,
+  { params }: { params: Promise<{ id: string }> },
+) {
+  const { id } = await params;
+  const product = await db.product.findUnique({ where: { id } });
+
+  if (!product) {
+    return NextResponse.json({ error: "Product not found" }, { status: 404 });
+  }
+
+  return NextResponse.json(product);
+}
+```
+
+### Pattern 8: Metadata and SEO
+
+```typescript
+// app/products/[slug]/page.tsx
+import { Metadata } from 'next'
+import { notFound } from 'next/navigation'
+
+type Props = {
+  params: Promise<{ slug: string }>
+}
+
+export async function generateMetadata({ params }: Props): Promise<Metadata> {
+  const { slug } = await params
+  const product = await getProduct(slug)
+
+  if (!product) return {}
+
+  return {
+    title: product.name,
+    description: product.description,
+    openGraph: {
+      title: product.name,
+      description: product.description,
+      images: [{ url: product.image, width: 1200, height: 630 }],
+    },
+    twitter: {
+      card: 'summary_large_image',
+      title: product.name,
+      description: product.description,
+      images: [product.image],
+    },
+  }
+}
+
+export async function generateStaticParams() {
+  const products = await db.product.findMany({ select: { slug: true } })
+  return products.map((p) => ({ slug: p.slug }))
+}
+
+export default async function ProductPage({ params }: Props) {
+  const { slug } = await params
+  const product = await getProduct(slug)
+
+  if (!product) notFound()
+
+  return <ProductDetail product={product} />
+}
+```
+
+## Caching Strategies
+
+### Data Cache
+
+```typescript
+// No cache (always fresh)
+fetch(url, { cache: "no-store" });
+
+// Cache forever (static)
+fetch(url, { cache: "force-cache" });
+
+// ISR - revalidate after 60 seconds
+fetch(url, { next: { revalidate: 60 } });
+
+// Tag-based invalidation
+fetch(url, { next: { tags: ["products"] } });
+
+// Invalidate via Server Action
+("use server");
+import { revalidateTag, revalidatePath } from "next/cache";
+
+export async function updateProduct(id: string, data: ProductData) {
+  await db.product.update({ where: { id }, data });
+  revalidateTag("products");
+  revalidatePath("/products");
+}
+```

package/.agents/skills/nextjs-developer/SKILL.md

@@ -0,0 +1,145 @@
+---
+name: nextjs-developer
+description: "Use when building Next.js 14+ applications with App Router, server components, or server actions. Invoke to configure route handlers, implement middleware, set up API routes, add streaming SSR, write generateMetadata for SEO, scaffold loading.tsx/error.tsx boundaries, or deploy to Vercel. Triggers on: Next.js, Next.js 14, App Router, RSC, use server, Server Components, Server Actions, React Server Components, generateMetadata, loading.tsx, Next.js deployment, Vercel, Next.js performance."
+license: MIT
+metadata:
+  author: https://github.com/Jeffallan
+  version: "1.1.0"
+  domain: frontend
+  triggers: Next.js, Next.js 14, App Router, Server Components, Server Actions, React Server Components, Next.js deployment, Vercel, Next.js performance
+  role: specialist
+  scope: implementation
+  output-format: code
+  related-skills: typescript-pro
+---
+
+# Next.js Developer
+
+Senior Next.js developer with expertise in Next.js 14+ App Router, server components, and full-stack deployment with focus on performance and SEO excellence.
+
+## Core Workflow
+
+1. **Architecture planning** — Define app structure, routes, layouts, rendering strategy
+2. **Implement routing** — Create App Router structure with layouts, templates, loading/error states
+3. **Data layer** — Set up server components, data fetching, caching, revalidation
+4. **Optimize** — Images, fonts, bundles, streaming, edge runtime
+5. **Deploy** — Production build, environment setup, monitoring
+   - Validate: run `next build` locally, confirm zero type errors, check `NEXT_PUBLIC_*` and server-only env vars are set, run Lighthouse/PageSpeed to confirm Core Web Vitals > 90
+
+## Reference Guide
+
+Load detailed guidance based on context:
+
+| Topic | Reference | Load When |
+|-------|-----------|-----------|
+| App Router | `references/app-router.md` | File-based routing, layouts, templates, route groups |
+| Server Components | `references/server-components.md` | RSC patterns, streaming, client boundaries |
+| Server Actions | `references/server-actions.md` | Form handling, mutations, revalidation |
+| Data Fetching | `references/data-fetching.md` | fetch, caching, ISR, on-demand revalidation |
+| Deployment | `references/deployment.md` | Vercel, self-hosting, Docker, optimization |
+
+## Constraints
+
+### MUST DO (Next.js-specific)
+- Use App Router (`app/` directory), never Pages Router (`pages/`)
+- Keep components as Server Components by default; add `'use client'` only at the leaf boundary where interactivity is required
+- Use native `fetch` with explicit `cache` / `next.revalidate` options — do not rely on implicit caching
+- Use `generateMetadata` (or the static `metadata` export) for all SEO — never hardcode `<title>` or `<meta>` tags in JSX
+- Optimize every image with `next/image`; never use a plain `<img>` tag for content images
+- Add `loading.tsx` and `error.tsx` at every route segment that performs async data fetching
+
+### MUST NOT DO
+- Convert components to Client Components just to access data — fetch server-side first
+- Skip `loading.tsx`/`error.tsx` boundaries on async route segments
+- Deploy without running `next build` to confirm zero errors
+
+## Code Examples
+
+### Server Component with data fetching and caching
+```tsx
+// app/products/page.tsx
+import { Suspense } from 'react'
+
+async function ProductList() {
+  // Revalidate every 60 seconds (ISR)
+  const res = await fetch('https://api.example.com/products', {
+    next: { revalidate: 60 },
+  })
+  if (!res.ok) throw new Error('Failed to fetch products')
+  const products: Product[] = await res.json()
+
+  return (
+    <ul>
+      {products.map((p) => (
+        <li key={p.id}>{p.name}</li>
+      ))}
+    </ul>
+  )
+}
+
+export default function Page() {
+  return (
+    <Suspense fallback={<p>Loading…</p>}>
+      <ProductList />
+    </Suspense>
+  )
+}
+```
+
+### Server Action with form handling and revalidation
+```tsx
+// app/products/actions.ts
+'use server'
+
+import { revalidatePath } from 'next/cache'
+
+export async function createProduct(formData: FormData) {
+  const name = formData.get('name') as string
+  await db.product.create({ data: { name } })
+  revalidatePath('/products')
+}
+
+// app/products/new/page.tsx
+import { createProduct } from '../actions'
+
+export default function NewProductPage() {
+  return (
+    <form action={createProduct}>
+      <input name="name" placeholder="Product name" required />
+      <button type="submit">Create</button>
+    </form>
+  )
+}
+```
+
+### generateMetadata for dynamic SEO
+```tsx
+// app/products/[id]/page.tsx
+import type { Metadata } from 'next'
+
+export async function generateMetadata(
+  { params }: { params: { id: string } }
+): Promise<Metadata> {
+  const product = await fetchProduct(params.id)
+  return {
+    title: product.name,
+    description: product.description,
+    openGraph: { title: product.name, images: [product.imageUrl] },
+  }
+}
+```
+
+## Output Templates
+
+When implementing Next.js features, provide:
+1. App structure (route organization)
+2. Layout/page components with proper data fetching
+3. Server actions if mutations needed
+4. Configuration (`next.config.js`, TypeScript)
+5. Brief explanation of rendering strategy chosen
+
+## Knowledge Reference
+
+Next.js 14+, App Router, React Server Components, Server Actions, Streaming SSR, Partial Prerendering, next/image, next/font, Metadata API, Route Handlers, Middleware, Edge Runtime, Turbopack, Vercel deployment
+
+[Documentation](https://jeffallan.github.io/claude-skills/skills/frontend/nextjs-developer/)