Always use the Next.js App Router (app/ directory).
Never create files in pages/. Use file-based routing with
app/route-name/page.tsx for pages and app/route-name/layout.tsx
for layouts. Use loading.tsx, error.tsx, and not-found.tsx
for built-in UI states.

// ❌ Bad: Pages Router pattern
// pages/dashboard.tsx
import { GetServerSideProps } from 'next';

export const getServerSideProps: GetServerSideProps = async (ctx) => {
  const session = await getSession(ctx);
  const stats = await fetchDashboardStats(session.user.id);

  return {
    props: { session, stats },
  };
};

export default function Dashboard({ session, stats }) {
  return (
    <div>
      <h1>Welcome, {session.user.name}</h1>
      <StatsGrid stats={stats} />
    </div>
  );
}

// ✅ Good: App Router with server component
// app/dashboard/page.tsx
import { getSession } from '@/lib/auth';
import { fetchDashboardStats } from '@/lib/data';
import { StatsGrid } from '@/components/StatsGrid';

export default async function DashboardPage() {
  const session = await getSession();
  const stats = await fetchDashboardStats(session.user.id);

  return (
    <div>
      <h1>Welcome, {session.user.name}</h1>
      <StatsGrid stats={stats} />
    </div>
  );
}

All components are React Server Components by default.
Only add "use client" when the component uses browser APIs,
React hooks (useState, useEffect, useRef, etc.), or event
handlers (onClick, onChange, etc.). Never put "use client"
at the top of page.tsx or layout.tsx unless absolutely required.
Push "use client" to the smallest leaf component possible.

// ❌ Bad: entire page is a client component for no reason
// app/products/page.tsx
"use client";

import { useState, useEffect } from 'react';

export default function ProductsPage() {
  const [products, setProducts] = useState([]);

  useEffect(() => {
    fetch('/api/products')
      .then(res => res.json())
      .then(setProducts);
  }, []);

  return (
    <div>
      <h1>Products</h1>
      {products.map(product => (
        <div key={product.id}>
          <h3>{product.name}</h3>
          <p>${product.price}</p>
          <AddToCartButton productId={product.id} />
        </div>
      ))}
    </div>
  );
}

// ✅ Good: Server Component page with a client leaf
// app/products/page.tsx
import { db } from '@/lib/db';
import { AddToCartButton } from '@/components/AddToCartButton';

export default async function ProductsPage() {
  const products = await db.product.findMany({
    orderBy: { createdAt: 'desc' },
  });

  return (
    <div>
      <h1>Products</h1>
      {products.map(product => (
        <div key={product.id}>
          <h3>{product.name}</h3>
          <p>${product.price}</p>
          <AddToCartButton productId={product.id} />
        </div>
      ))}
    </div>
  );
}

// components/AddToCartButton.tsx
"use client";

import { useState } from 'react';

export function AddToCartButton({ productId }: { productId: string }) {
  const [adding, setAdding] = useState(false);

  async function handleClick() {
    setAdding(true);
    await fetch('/api/cart', {
      method: 'POST',
      body: JSON.stringify({ productId }),
    });
    setAdding(false);
  }

  return (
    <button onClick={handleClick} disabled={adding}>
      {adding ? 'Adding...' : 'Add to Cart'}
    </button>
  );
}

Always use TypeScript with strict mode enabled.
Never use `any` type. Use `unknown` for truly unknown types
and narrow with type guards. Define explicit return types
for all API route handlers and server actions. Use Zod schemas
to derive types from validation where possible.

// ❌ Bad: any types everywhere, no strict mode
export async function POST(req: any) {
  const data = await req.json();
  const user = await createUser(data);
  return Response.json(user);
}

function formatPrice(price: any) {
  return '$' + price.toFixed(2); // runtime crash if price is a string
}

async function getUser(id: any) {
  const res = await fetch(`/api/users/${id}`);
  const data: any = await res.json();
  return data;
}

// ✅ Good: strict types, explicit return types
import { NextRequest, NextResponse } from 'next/server';
import { z } from 'zod';

const CreateUserSchema = z.object({
  name: z.string().min(1),
  email: z.string().email(),
  role: z.enum(['admin', 'user']),
});

type CreateUserInput = z.infer<typeof CreateUserSchema>;

export async function POST(req: NextRequest): Promise<NextResponse> {
  const body: unknown = await req.json();
  const data = CreateUserSchema.parse(body);
  const user = await createUser(data);
  return NextResponse.json(user);
}

function formatPrice(price: number): string {
  return '$' + price.toFixed(2);
}

async function getUser(id: string): Promise<User> {
  const res = await fetch(`/api/users/${id}`);
  const data: unknown = await res.json();
  return UserSchema.parse(data);
}

All API route handlers (app/api/**/route.ts) must validate
incoming data using Zod schemas. Never access req.body or
req.json() fields directly without validation. Always return
proper HTTP status codes. Always handle validation errors
with a 400 response including the error details.

// ❌ Bad: no validation, trusting req.body blindly
// app/api/orders/route.ts
export async function POST(req: Request) {
  const { productId, quantity, shippingAddress } = await req.json();

  const order = await db.order.create({
    data: {
      productId,
      quantity,
      shippingAddress,
      total: quantity * (await getProductPrice(productId)),
    },
  });

  return Response.json(order);
}

// ✅ Good: Zod validation, proper error handling
// app/api/orders/route.ts
import { NextRequest, NextResponse } from 'next/server';
import { z } from 'zod';

const CreateOrderSchema = z.object({
  productId: z.string().uuid(),
  quantity: z.number().int().min(1).max(99),
  shippingAddress: z.object({
    street: z.string().min(1),
    city: z.string().min(1),
    state: z.string().length(2),
    zip: z.string().regex(/^\d{5}(-\d{4})?$/),
  }),
});

export async function POST(req: NextRequest): Promise<NextResponse> {
  const body: unknown = await req.json();
  const result = CreateOrderSchema.safeParse(body);

  if (!result.success) {
    return NextResponse.json(
      { error: 'Invalid request', details: result.error.flatten() },
      { status: 400 }
    );
  }

  const { productId, quantity, shippingAddress } = result.data;

  const order = await db.order.create({
    data: {
      productId,
      quantity,
      shippingAddress,
      total: quantity * (await getProductPrice(productId)),
    },
  });

  return NextResponse.json(order, { status: 201 });
}

Always use the next/image component (import Image from 'next/image')
for all images. Never use the HTML <img> tag. Always provide width
and height props, or use fill with a sized parent container.
Always include a descriptive alt attribute. Use priority prop
for above-the-fold images (hero, LCP).

// ❌ Bad: plain img tags, no optimization
function ProductCard({ product }) {
  return (
    <div>
      <img src={product.imageUrl} />
      <h3>{product.name}</h3>
      <p>${product.price}</p>
    </div>
  );
}

function HeroSection() {
  return (
    <section>
      <img
        src="/hero-banner.png"
        style={{ width: '100%', height: 'auto' }}
      />
      <h1>Welcome to our store</h1>
    </section>
  );
}

// ✅ Good: next/image with proper optimization
import Image from 'next/image';

function ProductCard({ product }: { product: Product }) {
  return (
    <div>
      <Image
        src={product.imageUrl}
        alt={product.name}
        width={400}
        height={300}
        className="rounded-lg object-cover"
      />
      <h3>{product.name}</h3>
      <p>${product.price}</p>
    </div>
  );
}

function HeroSection() {
  return (
    <section className="relative h-[500px]">
      <Image
        src="/hero-banner.png"
        alt="Store hero banner with featured products"
        fill
        className="object-cover"
        priority
      />
      <h1 className="relative z-10">Welcome to our store</h1>
    </section>
  );
}

Environment variables without the NEXT_PUBLIC_ prefix are
server-only and must never be imported in client components.
API keys, database URLs, and secrets must never use NEXT_PUBLIC_.
For client-side config, use NEXT_PUBLIC_ prefix and never put
sensitive values in them. Always access env vars through a
centralized config file with validation, never inline process.env.

// ❌ Bad: secrets exposed to the client
// .env
NEXT_PUBLIC_DATABASE_URL=postgresql://admin:secret@db.example.com:5432/prod
NEXT_PUBLIC_STRIPE_SECRET_KEY=sk_live_abc123
NEXT_PUBLIC_JWT_SECRET=super-secret-jwt-key

// components/PaymentForm.tsx
"use client";

export function PaymentForm() {
  async function handleSubmit(data: FormData) {
    // Stripe secret key is in the client bundle!
    const res = await fetch('https://api.stripe.com/v1/charges', {
      headers: {
        Authorization: `Bearer ${process.env.NEXT_PUBLIC_STRIPE_SECRET_KEY}`,
      },
      body: data,
    });
  }

  return <form onSubmit={handleSubmit}>...</form>;
}

// ✅ Good: server-only secrets, validated config
// .env
DATABASE_URL=postgresql://admin:secret@db.example.com:5432/prod
STRIPE_SECRET_KEY=sk_live_abc123
JWT_SECRET=super-secret-jwt-key
NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY=pk_live_xyz789
NEXT_PUBLIC_APP_URL=https://myapp.com

// lib/env.ts
import { z } from 'zod';

const serverSchema = z.object({
  DATABASE_URL: z.string().url(),
  STRIPE_SECRET_KEY: z.string().startsWith('sk_'),
  JWT_SECRET: z.string().min(32),
});

const clientSchema = z.object({
  NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY: z.string().startsWith('pk_'),
  NEXT_PUBLIC_APP_URL: z.string().url(),
});

export const serverEnv = serverSchema.parse(process.env);
export const clientEnv = clientSchema.parse({
  NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY: process.env.NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY,
  NEXT_PUBLIC_APP_URL: process.env.NEXT_PUBLIC_APP_URL,
});

// app/api/payment/route.ts — server only
import { serverEnv } from '@/lib/env';

export async function POST(req: NextRequest): Promise<NextResponse> {
  const stripe = new Stripe(serverEnv.STRIPE_SECRET_KEY);
  // Secret key never leaves the server
}

# Next.js Rules

## Routing
- Always use App Router (app/ directory), never Pages Router (pages/)
- Use file conventions: page.tsx, layout.tsx, loading.tsx, error.tsx, not-found.tsx
- Never use getServerSideProps, getStaticProps, or getInitialProps

## Server vs Client Components
- All components are Server Components by default
- Only add "use client" for components using hooks, event handlers, or browser APIs
- Push "use client" to the smallest leaf component possible
- Never put "use client" on page.tsx or layout.tsx unless absolutely required

## TypeScript
- Always use strict mode
- Never use `any` — use `unknown` and narrow with type guards
- Define explicit return types for API routes and server actions
- Use Zod schemas to derive types where possible

## API Routes
- Validate all incoming data with Zod schemas
- Never access req.json() fields without validation
- Return proper HTTP status codes (400 for bad input, 201 for created)
- Always use safeParse and return error details on failure

## Images
- Always use next/image, never <img>
- Always provide width + height, or use fill with a sized parent
- Always include descriptive alt text
- Use priority for above-the-fold / LCP images

## Environment Variables
- Never use NEXT_PUBLIC_ for secrets (API keys, DB URLs, tokens)
- Access env vars through a centralized validated config, not inline process.env
- Validate all env vars at startup with Zod
- Only NEXT_PUBLIC_ vars are safe for client components