bun

bun create next-app my-app


## App Router Structure

app/ ├── layout.tsx # Root layout ├── page.tsx # Home page ├── proxy.ts # Auth proxy (replaces middleware.ts) ├── (auth)/ │ ├── login/page.tsx │ └── register/page.tsx ├── (dashboard)/ │ ├── layout.tsx │ └── page.tsx ├── api/ │ └── [...route]/route.ts └── globals.css


## Key Concepts

| Concept | Guide |
|---------|-------|
| **Dynamic Routes (Async Params)** | [reference/dynamic-routes.md](reference/dynamic-routes.md) |
| **Server vs Client Components** | [reference/components.md](reference/components.md) |
| **proxy.ts (Auth)** | [reference/proxy.md](reference/proxy.md) |
| **Data Fetching** | [reference/data-fetching.md](reference/data-fetching.md) |
| **Caching** | [reference/caching.md](reference/caching.md) |
| **Route Handlers** | [reference/route-handlers.md](reference/route-handlers.md) |

## Examples

| Pattern | Guide |
|---------|-------|
| **Authentication Flow** | [examples/authentication.md](examples/authentication.md) |
| **Protected Routes** | [examples/protected-routes.md](examples/protected-routes.md) |
| **Forms & Actions** | [examples/forms-actions.md](examples/forms-actions.md) |
| **API Integration** | [examples/api-integration.md](examples/api-integration.md) |

## Templates

| Template | Purpose |
|----------|---------|
| [templates/proxy.ts](templates/proxy.ts) | Auth proxy template |
| [templates/layout.tsx](templates/layout.tsx) | Root layout with providers |
| [templates/page.tsx](templates/page.tsx) | Page component template |

## BREAKING CHANGES in Next.js 15/16

### 1. Async Params & SearchParams

**IMPORTANT**: `params` and `searchParams` are now Promises and MUST be awaited.

```tsx
// OLD (Next.js 14) - DO NOT USE
export default function Page({ params }: { params: { id: string } }) {
  return <div>Post {params.id}</div>;
}

// NEW (Next.js 15/16) - USE THIS
export default async function Page({
  params,
}: {
  params: Promise<{ id: string }>;
}) {
  const { id } = await params;
  return <div>Post {id}</div>;
}

Dynamic Route Examples

// app/posts/[id]/page.tsx
export default async function PostPage({
  params,
}: {
  params: Promise<{ id: string }>;
}) {
  const { id } = await params;
  const post = await getPost(id);

  return <article>{post.title}</article>;
}

// app/posts/[id]/edit/page.tsx - Nested dynamic route
export default async function EditPostPage({
  params,
}: {
  params: Promise<{ id: string }>;
}) {
  const { id } = await params;
  // ...
}

// app/[category]/[slug]/page.tsx - Multiple params
export default async function Page({
  params,
}: {
  params: Promise<{ category: string; slug: string }>;
}) {
  const { category, slug } = await params;
  // ...
}

SearchParams (Query String)

// app/search/page.tsx
export default async function SearchPage({
  searchParams,
}: {
  searchParams: Promise<{ q?: string; page?: string }>;
}) {
  const { q, page } = await searchParams;
  const results = await search(q, Number(page) || 1);

  return <SearchResults results={results} />;
}

Layout with Params

// app/posts/[id]/layout.tsx
export default async function PostLayout({
  children,
  params,
}: {
  children: React.ReactNode;
  params: Promise<{ id: string }>;
}) {
  const { id } = await params;

  return (
    <div>
      <nav>Post {id}</nav>
      {children}
    </div>
  );
}

generateMetadata with Async Params

// app/posts/[id]/page.tsx
import { Metadata } from "next";

export async function generateMetadata({
  params,
}: {
  params: Promise<{ id: string }>;
}): Promise<Metadata> {
  const { id } = await params;
  const post = await getPost(id);

  return {
    title: post.title,
    description: post.excerpt,
  };
}

generateStaticParams

// app/posts/[id]/page.tsx
export async function generateStaticParams() {
  const posts = await getPosts();

  return posts.map((post) => ({
    id: post.id.toString(),
  }));
}

2. proxy.ts Replaces middleware.ts

IMPORTANT: Next.js 16 replaces middleware.ts with proxy.ts. The proxy runs on Node.js runtime (not Edge).

// app/proxy.ts
import { NextRequest, NextResponse } from "next/server";

export function proxy(request: NextRequest) {
  const { pathname } = request.nextUrl;

  // Check auth for protected routes
  const token = request.cookies.get("better-auth.session_token");

  if (pathname.startsWith("/dashboard") && !token) {
    return NextResponse.redirect(new URL("/login", request.url));
  }

  return NextResponse.next();
}

export const config = {
  matcher: ["/dashboard/:path*", "/api/:path*"],
};

Server Components (Default)

// app/posts/page.tsx - Server Component by default
async function PostsPage() {
  const posts = await fetch("https://api.example.com/posts", {
    cache: "force-cache", // or "no-store"
  }).then(res => res.json());

  return (
    <ul>
      {posts.map((post) => (
        <li key={post.id}>{post.title}</li>
      ))}
    </ul>
  );
}

export default PostsPage;

Client Components

"use client";

import { useState } from "react";

export function Counter() {
  const [count, setCount] = useState(0);

  return (
    <button onClick={() => setCount(count + 1)}>
      Count: {count}
    </button>
  );
}

Server Actions

// app/actions.ts
"use server";

import { revalidatePath } from "next/cache";

export async function createPost(formData: FormData) {
  const title = formData.get("title") as string;

  await db.post.create({ data: { title } });

  revalidatePath("/posts");
}

// app/posts/new/page.tsx
import { createPost } from "../actions";

export default function NewPostPage() {
  return (
    <form action={createPost}>
      <input name="title" placeholder="Post title" />
      <button type="submit">Create</button>
    </form>
  );
}

Data Fetching Patterns

Parallel Data Fetching

async function Page() {
  const [user, posts] = await Promise.all([
    getUser(),
    getPosts(),
  ]);

  return <Dashboard user={user} posts={posts} />;
}

Sequential Data Fetching

async function Page() {
  const user = await getUser();
  const posts = await getUserPosts(user.id);

  return <Dashboard user={user} posts={posts} />;
}

Environment Variables

# .env.local
DATABASE_URL=postgresql://...
BETTER_AUTH_SECRET=your-secret
NEXT_PUBLIC_API_URL=http://localhost:8000

NEXT_PUBLIC_* - Exposed to browser
Without prefix - Server-only

Common Patterns

Layout with Auth Provider

// app/layout.tsx
import { AuthProvider } from "@/components/auth-provider";

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

Loading States

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

Error Handling

// app/posts/error.tsx
"use client";

export default function Error({
  error,
  reset,
}: {
  error: Error;
  reset: () => void;
}) {
  return (
    <div>
      <h2>Something went wrong!</h2>
      <button onClick={() => reset()}>Try again</button>
    </div>
  );
}

nextjs

Next.js 16 Skill

Quick Start

Installation