// app/api/users/route.ts
export async function GET(request: Request) {
  return Response.json({ users: [] });
}

export async function GET(request: Request) {
  return Response.json({ method: "GET" });
}

export async function POST(request: Request) {
  const data = await request.json();
  return Response.json({ created: data });
}

export async function POST(request: Request) {
  const data = await request.json();
  console.log(data); // { name: "Alice" }
  return Response.json({ success: true });
}

export async function POST(request: Request) {
  const formData = await request.formData();
  const file = formData.get("file");
  return Response.json({ uploaded: true });
}

export async function GET(request: Request) {
  const { searchParams } = new URL(request.url);
  const query = searchParams.get("q");
  return Response.json({ query });
}

const { name, email } = await request.json();
if (!name || !email) {
  return Response.json({ error: "name and email are required" }, { status: 400 });
}

export async function POST(request: Request) {
  const raw = await request.text(); // e.g. Stripe webhook payload
  const sig = request.headers.get("stripe-signature");
  return Response.json({ received: true });
}

import { prisma } from "@/lib/prisma";

export async function GET() {
  const users = await prisma.user.findMany();
  return Response.json(users);
}

export async function POST(request: Request) {
  try {
    const data = await request.json();
    if (!data.name) {
      return Response.json(
        { error: "Name required" },
        { status: 400 }
      );
    }
    return Response.json({ success: true });
  } catch (error) {
    return Response.json(
      { error: "Invalid request" },
      { status: 500 }
    );
  }
}

export async function GET(request: Request) {
  const token = request.headers.get("authorization");
  if (!token) {
    return Response.json({ error: "Unauthorized" }, { status: 401 });
  }
  return Response.json({ data: "protected" });
}

const apiKey = request.headers.get("x-api-key");
if (apiKey !== process.env.API_SECRET) {
  return Response.json({ error: "Forbidden" }, { status: 403 });
}

} catch (err) {
  console.error("[api/users] error:", err);
  return Response.json({ error: "Internal server error" }, { status: 500 });
}

"use client";
// ↑ must appear before any import statements
import { useState } from "react";

export default function Counter() {
  const [count, setCount] = useState(0);
  return <button onClick={() => setCount(count + 1)}>{count}</button>;
}

"use client";
// Both files below become part of the client bundle:
import { Chart } from "./Chart";       // ← client-side
import { DataGrid } from "./DataGrid";   // ← client-side

"use client";
// ❌ Pulls entire lodash into the client bundle
import _ from "lodash";

// ✅ Move heavy computation to a Server Component or Server Action

// Good: only the interactive button is a Client Component
// app/post/page.tsx — Server Component (no directive)
import { LikeButton } from "./LikeButton"; // only this file has "use client"
export default async function PostPage() {
  const post = await getPost();
  return <article>{post.body}<LikeButton id={post.id} /></article>;
}

// components/MapWrapper.tsx
"use client";
import { MapComponent } from "some-map-library"; // uses window internally
export default function MapWrapper({ center }) {
  return <MapComponent center={center} />;
}

"use client";
// ClientShell.tsx — the children prop can be a Server Component
export default function ClientShell({ children }) {
  return <div>{children}</div>;
}

// app/page.tsx (Server Component) — ServerSidebar stays on the server
<ClientShell><ServerSidebar /></ClientShell>

"use client";
// ❌ Cannot import a server component directly from a client file
import { ServerSidebar } from "./ServerSidebar"; // runtime error

// ❌ Plain server function cannot be passed as a prop
<ClientComp onClick={serverFunction} />

// ✅ Server Action CAN be passed as a prop
"use server";
export async function deleteItem(id: string) { await db.item.delete({ where: { id } }); }
// Then in a Server Component: <ClientComp action={deleteItem} />

// ✅ OK: strings, numbers, arrays, plain objects, Promises
<ClientChart data={data} title="Sales" />

// ❌ Not OK: class instances, Maps, Sets, functions (unless Server Actions)
<ClientComp handler={someClassInstance} />

# Open DevTools > Network > JS
# Server-only modules (db, secrets) should NOT appear in client chunks

app/
  posts/
    [id]/
      page.tsx

export default async function Post({ params }: { params: Promise<{ id: string }> }) {
  const { id } = await params;
  return <h1>Post {id}</h1>;
}

app/
  docs/
    [...slug]/
      page.tsx

export default async function Docs({ params }: { params: Promise<{ slug: string[] }> }) {
  const { slug } = await params;
  const path = slug.join("/");
  return <h1>{path}</h1>;
}

export async function generateStaticParams() {
  const posts = await getPosts();
  return posts.map((post) => ({
    id: post.id.toString(),
  }));
}

export default async function Post({ params }: { params: Promise<{ id: string }> }) {
  const { id } = await params;
  // This page is pre-built for every post at build time
  return <h1>Post {id}</h1>;
}

export const revalidate = 3600; // Rebuild every hour

# .env.local
NEXT_PUBLIC_API_URL=https://api.example.com
NEXT_PUBLIC_APP_NAME=My App

function Component() {
  const apiUrl = process.env.NEXT_PUBLIC_API_URL;
  return <p>API: {apiUrl}</p>;
}

// process.env.NEXT_PUBLIC_API_URL becomes a string literal in the bundle
const url = process.env.NEXT_PUBLIC_API_URL; // "https://api.example.com"

NEXT_PUBLIC_STRIPE_KEY=pk_live_abc123
NEXT_PUBLIC_GA_ID=G-XXXXXXX

// next.config.js
module.exports = {
  env: {
    APP_VERSION: process.env.npm_package_version, // inlined at build time
    FEATURE_FLAG: process.env.FEATURE_FLAG
  }
};

// next.config.js
module.exports = {
  serverRuntimeConfig: {
    mySecret: process.env.MY_SECRET // server-only, not in browser
  },
  publicRuntimeConfig: {
    apiUrl: process.env.NEXT_PUBLIC_API_URL // shared with client
  }
};

// lib/env.ts — imported in app/layout.tsx
const required = ["DATABASE_URL", "AUTH_SECRET"];
for (const key of required) {
  if (!process.env[key]) throw new Error(`Missing env var: ${key}`);
}

import { createEnv } from "@t3-oss/env-nextjs";
import { z } from "zod";

export const env = createEnv({
  server: { DATABASE_URL: z.string().url() },
  client: { NEXT_PUBLIC_API_URL: z.string().url() },
  runtimeEnv: process.env
});

# After editing .env.local or adding new variables:
npm run dev  # restart required for new vars to take effect

Create routes by adding a folder and a page.tsx file inside it.

app/
  page.tsx              # / route
  about/
    page.tsx            # /about route
  blog/
    page.tsx            # /blog route
    [slug]/
      page.tsx          # /blog/:slug route

Map URL path segments directly to folder names in the app directory.

app/users/[id]/posts/page.tsx  →  /users/:id/posts

Add a root layout.tsx to wrap every page with shared HTML structure.

// app/layout.tsx
export default function RootLayout({ children }: { children: React.ReactNode }) {
  return <html lang="en"><body>{children}</body></html>;
}

Use page.tsx for visible UI and route.ts for API route handlers.

app/
  api/
    users/
      route.ts    # GET /api/users, POST /api/users
  users/
    page.tsx      # /users page rendered in the browser

Add a loading.tsx next to any page to show a Suspense fallback.

// app/blog/loading.tsx
export default function Loading() {
  return <p>Loading posts...</p>;
}

Use dynamic [slug] segments to match variable URL parts — in Next.js 15, params is a Promise.

// app/blog/[slug]/page.tsx
export default async function Post({ params }: { params: Promise<{ slug: string }> }) {
  const { slug } = await params;
  return <h1>Post: {slug}</h1>;
}

Wrap folder names in parentheses to exclude them from the URL path.

app/
  (marketing)/
    page.tsx          # / (still at root URL)
    about/page.tsx    # /about
    contact/page.tsx  # /contact
  (dashboard)/
    layout.tsx        # separate layout, no URL impact
    page.tsx          # /dashboard

Give each route group its own layout for auth vs app separation.

app/
  (auth)/
    layout.tsx        # auth layout with centered card
    login/page.tsx    # /login
    signup/page.tsx   # /signup
  (app)/
    layout.tsx        # app layout with sidebar nav
    dashboard/page.tsx

Scope middleware-like access control by grouping protected routes.

app/
  (protected)/
    dashboard/page.tsx
    settings/page.tsx
  (public)/
    page.tsx
    about/page.tsx

Define a layout per group without affecting the URL structure.

// app/(auth)/layout.tsx
export default function AuthLayout({ children }: { children: React.ReactNode }) {
  return <main className="auth-bg">{children}</main>;
}

Combine route groups with parallel routes using the @ prefix.

app/
  (dashboard)/
    @analytics/page.tsx
    @overview/page.tsx
    layout.tsx

Use feature folders to group all files for one domain in one place.

app/
  features/
    auth/
      page.tsx
      components/
      hooks/
      utils.ts
    posts/
      page.tsx
      components/
      hooks/

Keep all Next.js special files inside the feature folder.

features/users/
  page.tsx
  layout.tsx
  error.tsx
  loading.tsx
  components/
    UserCard.tsx
  hooks/
    useUser.ts

Create barrel files with index.ts to simplify imports from feature folders.

// features/auth/index.ts
export { LoginForm } from "./components/LoginForm";
export { useAuth } from "./hooks/useAuth";

Place server actions in a dedicated actions/ folder inside each feature.

features/posts/
  actions/
    createPost.ts
    deletePost.ts
  components/
  page.tsx

Put cross-feature utilities in a root lib/ folder accessible to all routes.

lib/
  format.ts      # shared date/number formatting
  fetcher.ts     # shared fetch wrapper
  constants.ts   # app-wide constants

import { Inter, Playfair_Display } from "next/font/google";

const inter = Inter({ subsets: ["latin"] });
const playfair = Playfair_Display({
  weight: ["400", "700"],
  subsets: ["latin"]
});

export default function Page() {
  return (
    <div>
      <h1 className={playfair.className}>Title</h1>
      <p className={inter.className}>Body text</p>
    </div>
  );
}

const inter = Inter({ subsets: ["latin"], variable: "--font-inter" });

export default function RootLayout({ children }) {
  return <html className={inter.variable}>{children}</html>;
}
// In CSS: font-family: var(--font-inter);

// lib/fonts.ts
import { Inter, Roboto_Mono } from "next/font/google";

export const inter = Inter({ subsets: ["latin"] });
export const mono = Roboto_Mono({ subsets: ["latin"] });

import localFont from "next/font/local";

const customFont = localFont({
  src: [
    {
      path: "../fonts/custom.woff2",
      weight: "400",
      style: "normal"
    },
    {
      path: "../fonts/custom-bold.woff2",
      weight: "700",
      style: "normal"
    }
  ]
});

public/
  fonts/
    custom.woff2
    custom-bold.woff2

export default function RootLayout({ children }) {
  return (
    <html className={customFont.className}>
      <body>{children}</body>
    </html>
  );
}

const customFont = localFont({
  src: "../fonts/custom.woff2",
  variable: "--font-custom"
});
// tailwind.config: fontFamily: { brand: ["var(--font-custom)"] }

npx create-next-app@latest my-app
cd my-app
npm run dev

npx create-next-app@latest my-app --ts --app --tailwind

npm install && npm run dev

// app/page.tsx
export default function Home() {
  return (
    <main>
      <h1>Welcome to Next.js</h1>
      <p>Get started by editing this page</p>
    </main>
  );
}

// app/about/page.tsx
export default function About() {
  return <h1>About Us</h1>;
}

export default async function Blog() {
  const posts = await getPosts();
  return <ul>{posts.map(p => <li key={p.id}>{p.title}</li>)}</ul>;
}

export const metadata = {
  title: "Home",
  description: "Welcome to my Next.js site"
};

"use client";
import { useState } from "react";

export default function Counter() {
  const [count, setCount] = useState(0);
  return <button onClick={() => setCount(count + 1)}>Count: {count}</button>;
}

npm install -D tailwindcss postcss autoprefixer
npx tailwindcss init -p

import Link from "next/link";

export default function Nav() {
  return <nav><Link href="/about">About</Link></nav>;
}

npm install prisma @prisma/client
npx prisma init
npx prisma db push  # sync schema to database

npm install next-auth
# or
npm install @clerk/nextjs

import Image from "next/image";
<Image src="/hero.jpg" alt="Hero" width={1200} height={600} priority />

import Image from 'next/image';
import heroImage from '@/public/hero.jpg';

<Image src={heroImage} alt="Hero" />

// next.config.js
module.exports = {
  images: {
    remotePatterns: [{ hostname: "cdn.example.com", pathname: "/uploads/**" }]
  }
};

module.exports = {
  images: {
    remotePatterns: [
      { hostname: "cdn.example.com" },
      { hostname: "images.example.com", protocol: "https" }
    ]
  }
};

import logo from '@/public/logo.png'; // width/height inferred
<Image src={logo} alt="Logo" />

<Image
  src="/icon.svg"
  alt="Icon"
  width={32}
  height={32}
  unoptimized
/>

<Image
  src="/below-fold.jpg"
  alt="Below fold image"
  width={800}
  height={600}
  loading="lazy" // Default behavior
/>

<Image
  src="/hero.jpg"
  alt="Hero"
  width={1200}
  height={600}
  priority // Load immediately
/>

<Image
  src="/logo.png"
  alt="Logo"
  width={120}
  height={40}
  loading="eager" // Don't defer
/>

<Image
  src="/infographic.png"
  alt="Infographic"
  width={800}
  height={600}
  // loading="lazy" is the default — no need to set it explicitly
/>

import Link from "next/link";

export default function Navigation() {
  return (
    <nav>
      <Link href="/">Home</Link>
      <Link href="/about">About</Link>
      <Link href="/blog">Blog</Link>
    </nav>
  );
}

<Link href="/contact" className="nav-link">Contact</Link>

<Link href="/about" prefetch={true}>
  About
</Link>

<Link href="/api/heavy-data" prefetch={false}>
  Load Data
</Link>

import { useRouter } from "next/navigation";

const router = useRouter();

function prefetchAbout() {
  router.prefetch("/about");
}

"use client";

import { usePathname } from "next/navigation";
import Link from "next/link";

export default function Navigation() {
  const pathname = usePathname();
  
  return (
    <nav>
      <Link
        href="/"
        className={pathname === "/" ? "active" : ""}
      >
        Home
      </Link>
      <Link
        href="/about"
        className={pathname === "/about" ? "active" : ""}
      >
        About
      </Link>
    </nav>
  );
}