nextjs-16-conventions

name: Next.js 16+ Conventions description: This skill should be used when working with Next.js 16+ codebases, when the user asks about "Next.js routing", "App Router", "Server Components", "Client Components", "Server Actions", "Next.js API routes", "Next.js layouts", or when EREN detects a Next.js project. Provides modern Next.js 16+ patterns and best practices. version: 0.1.0

Next.js 16+ Conventions

Next.js 16+ builds upon the App Router paradigm with enhanced Server Components, improved caching, and streamlined data fetching. This skill provides decision trees and patterns for working with Next.js 16+ codebases effectively.

Core Principles

Next.js 16+ emphasizes:

• Server Components as the default (zero client JS)
• App Router with file-based routing conventions
• Server Actions for mutations and form handling
• Streaming and Suspense for progressive loading
• Built-in caching with fine-grained control

Server vs Client Components

Decision Tree: Component Type

1. Does it use browser APIs (window, localStorage)? → Client Component
2. Does it use React hooks (useState, useEffect)? → Client Component
3. Does it need event handlers (onClick)? → Client Component
4. Does it fetch data at render time? → Server Component
5. Does it access backend resources directly? → Server Component
6. Is it purely presentational? → Server Component (default)

Server Component (Default)

// app/users/page.tsx - Server Component (no directive needed)
import { db } from '@/lib/db';

export default async function UsersPage() {
  const users = await db.user.findMany();

  return (
    <div>
      <h1>Users</h1>
      <ul>
        {users.map(user => (
          <li key={user.id}>{user.name}</li>
        ))}
      </ul>
    </div>
  );
}

Client Component

// app/components/counter.tsx - Client Component
'use client';

import { useState } from 'react';

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

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

Composition Pattern

Server Components can import Client Components, not vice versa:

// app/dashboard/page.tsx - Server Component
import { db } from '@/lib/db';
import { InteractiveChart } from './interactive-chart'; // Client Component

export default async function DashboardPage() {
  const data = await db.analytics.getChartData();

  return (
    <div>
      <h1>Dashboard</h1>
      {/* Pass server data to client component */}
      <InteractiveChart data={data} />
    </div>
  );
}

App Router File Conventions

Route Files

Directory Structure

app/
├── layout.tsx              # Root layout
├── page.tsx                # Home page (/)
├── globals.css
├── (auth)/                 # Route group (no URL impact)
│   ├── login/
│   │   └── page.tsx        # /login
│   └── register/
│       └── page.tsx        # /register
├── dashboard/
│   ├── layout.tsx          # Dashboard layout
│   ├── page.tsx            # /dashboard
│   ├── loading.tsx         # Loading state
│   └── [teamId]/           # Dynamic segment
│       ├── page.tsx        # /dashboard/[teamId]
│       └── settings/
│           └── page.tsx    # /dashboard/[teamId]/settings
└── api/
    └── users/
        └── route.ts        # API: /api/users

Decision Tree: Route Organization

1. Shared UI across routes? → Create layout.tsx in parent
2. Routes with shared logic but different URLs? → Use route groups (folder)
3. Dynamic path segment? → Use [param] folder
4. Catch-all segments? → Use [...slug] or [[...slug]]
5. API endpoint? → Create route.ts (not page.tsx)

Server Actions

Server Actions handle mutations directly from components.

Form Action Pattern

// app/users/actions.ts
'use server';

import { db } from '@/lib/db';
import { revalidatePath } from 'next/cache';

export async function createUser(formData: FormData) {
  const name = formData.get('name') as string;
  const email = formData.get('email') as string;

  await db.user.create({
    data: { name, email }
  });

  revalidatePath('/users');
}

// app/users/create/page.tsx - Server Component
import { createUser } from '../actions';

export default function CreateUserPage() {
  return (
    <form action={createUser}>
      <input name="name" placeholder="Name" required />
      <input name="email" type="email" placeholder="Email" required />
      <button type="submit">Create User</button>
    </form>
  );
}

Client-Side Server Action

// app/components/delete-button.tsx
'use client';

import { deleteUser } from '../actions';
import { useTransition } from 'react';

export function DeleteButton({ userId }: { userId: string }) {
  const [isPending, startTransition] = useTransition();

  return (
    <button
      disabled={isPending}
      onClick={() => startTransition(() => deleteUser(userId))}
    >
      {isPending ? 'Deleting...' : 'Delete'}
    </button>
  );
}

Decision Tree: Server Actions

1. Simple form submission? → Use action attribute directly
2. Need loading state? → Use useTransition in Client Component
3. Need form validation? → Use useActionState hook
4. Need optimistic updates? → Use useOptimistic hook
5. Revalidate after mutation? → Call revalidatePath or revalidateTag

Data Fetching

Fetch in Server Components

// app/posts/page.tsx
async function getPosts() {
  const res = await fetch('https://api.example.com/posts', {
    next: { revalidate: 3600 } // Revalidate every hour
  });
  return res.json();
}

export default async function PostsPage() {
  const posts = await getPosts();
  return <PostList posts={posts} />;
}

Caching Options

Parallel Data Fetching

// Fetch in parallel, not sequentially
export default async function DashboardPage() {
  const [users, posts, analytics] = await Promise.all([
    getUsers(),
    getPosts(),
    getAnalytics()
  ]);

  return (
    <Dashboard users={users} posts={posts} analytics={analytics} />
  );
}

Layouts and Templates

Root Layout (Required)

// app/layout.tsx
import type { Metadata } from 'next';

export const metadata: Metadata = {
  title: 'My App',
  description: 'App description'
};

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

Nested Layouts

// app/dashboard/layout.tsx
export default function DashboardLayout({
  children
}: {
  children: React.ReactNode;
}) {
  return (
    <div className="dashboard">
      <Sidebar />
      <div className="content">{children}</div>
    </div>
  );
}

API Routes

Route Handler

// app/api/users/route.ts
import { NextRequest, NextResponse } from 'next/server';
import { db } from '@/lib/db';

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

export async function POST(request: NextRequest) {
  const body = await request.json();
  const user = await db.user.create({ data: body });
  return NextResponse.json(user, { status: 201 });
}

Dynamic Route Handler

// app/api/users/[id]/route.ts
import { NextRequest, NextResponse } from 'next/server';

export async function GET(
  request: NextRequest,
  { params }: { params: { id: string } }
) {
  const user = await db.user.findUnique({
    where: { id: params.id }
  });

  if (!user) {
    return NextResponse.json({ error: 'Not found' }, { status: 404 });
  }

  return NextResponse.json(user);
}

Error Handling

Error Boundary

// app/dashboard/error.tsx
'use client';

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

Not Found

// app/users/[id]/page.tsx
import { notFound } from 'next/navigation';

export default async function UserPage({ params }: { params: { id: string } }) {
  const user = await getUser(params.id);

  if (!user) {
    notFound();
  }

  return <UserProfile user={user} />;
}

Streaming and Suspense

Loading UI

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

Streaming with Suspense

// app/dashboard/page.tsx
import { Suspense } from 'react';

export default function DashboardPage() {
  return (
    <div>
      <h1>Dashboard</h1>
      <Suspense fallback={<ChartSkeleton />}>
        <SlowChart />
      </Suspense>
      <Suspense fallback={<TableSkeleton />}>
        <SlowTable />
      </Suspense>
    </div>
  );
}

Additional Resources

Reference Files

For detailed patterns:

• references/caching-strategies.md - Advanced caching patterns
• references/authentication.md - Auth patterns with Next.js
• references/testing-patterns.md - Testing Next.js 16+ apps

Key Points

• Server Components are the default—add 'use client' only when needed
• Use Server Actions for mutations instead of API routes
• Leverage streaming and Suspense for better UX
• Use route groups to organize without affecting URLs
• Parallel fetch data when possible