Next.js App Router skill for Codex

Done well means: each URL maps to a predictable folder, shared UI lives in the right layout, every segment that can be slow or fail has a loading or error boundary at the level users expect, params are awaited, and the build output shows the routes rendering the way you intended (static, dynamic, or partially prerendered).

Before changing routes

1. Read AGENTS.md, package.json (Next.js version) and next.config.*.
2. Note version-specific rules:
   • Next 15+: params, searchParams, cookies(), headers() and draftMode() are async. Next 16 removed the synchronous fallback.
   • Next 16: middleware.ts is renamed proxy.ts (exported function proxy); every parallel route slot needs an explicit default.tsx; next lint is gone (call ESLint directly).
   • Next 15.5+: next typegen and the build generate global PageProps<'/route'>, LayoutProps<'/route'> and RouteContext<'/route'> helpers.
3. List the existing tree: find app -name "*.tsx" -o -name "*.ts" | sort (or src/app).
4. Check whether cacheComponents is enabled; it changes how data access must be wrapped. For caching decisions use the nextjs-caching skill.

File conventions

File	Role	Notes
layout.tsx	UI shared by a segment and children	Persists across navigations; does not re-render or receive searchParams
page.tsx	Makes the segment routable	Receives params and searchParams promises
loading.tsx	Suspense fallback for the segment’s page and children	Does not wrap the layout of the same segment
error.tsx	Error boundary for the segment	Must be a client component; gets error and reset
global-error.tsx	Catches errors in the root layout	Must render its own <html> and <body>
not-found.tsx	UI for notFound() and unmatched URLs	Root app/not-found.tsx handles global 404s
template.tsx	Like layout but remounts on navigation	Use for per-page enter animations or resetting state
default.tsx	Fallback for a parallel slot on hard navigation	Required per slot in Next 16
route.ts	HTTP handler	Cannot coexist with page.tsx in the same segment

Folder conventions: (group) organizes without a URL segment and can give sections different root layouts; _private opts a folder out of routing; [id] dynamic, [...slug] catch-all, [[...slug]] optional catch-all; @slot parallel route; (.), (..), (...) intercepting routes.

Pages and layouts

// app/blog/[slug]/page.tsx
import { notFound } from "next/navigation";
import type { Metadata } from "next";
import { getPost } from "@/lib/posts";

export async function generateStaticParams() {
  const posts = await listPublishedSlugs();
  return posts.map((slug) => ({ slug }));
}

export async function generateMetadata({ params }: PageProps<"/blog/[slug]">): Promise<Metadata> {
  const { slug } = await params;
  const post = await getPost(slug);
  return post ? { title: post.title, description: post.excerpt } : {};
}

export default async function Page({ params }: PageProps<"/blog/[slug]">) {
  const { slug } = await params;
  const post = await getPost(slug); // wrap getPost in React.cache to share with metadata
  if (!post) notFound();
  return <Article post={post} />;
}

If the project is on a version without the generated helpers, type props inline: { params: Promise<{ slug: string }> }.

Layout rules:

• The root layout must render <html> and <body>. Put providers in a separate client component, not in the layout file itself.
• Layouts cannot read the current pathname on the server. Use usePathname() in a client child for active-link styling.
• Data a layout and its page both need: fetch in both through a React.cache-wrapped function; do not try to pass props from layout to page.

Loading and error boundaries

• loading.tsx in app/dashboard/ shows while dashboard/page.tsx and nested segments load, but the dashboard/layout.tsx itself renders outside that boundary. If the layout awaits slow data, the fallback never appears: move that fetch into a Suspense- wrapped child.
• For finer streaming, add <Suspense> around individual slow components instead of relying on a single route-level loading.tsx.
• error.tsx catches errors from its segment’s page and children, not from the layout in the same folder. To catch layout errors, place error.tsx in the parent segment.
• notFound(), redirect() and permanentRedirect() throw special errors. Never call them inside a try block whose catch swallows everything; re-throw or call them after the try.

// app/dashboard/error.tsx
"use client";
export default function Error({ error, reset }: { error: Error & { digest?: string }; reset: () => void }) {
  return (
    <div role="alert">
      <p>Something went wrong loading the dashboard.</p>
      <button onClick={() => reset()}>Try again</button>
    </div>
  );
}

In production, error.message from server components is replaced by a generic message; use error.digest to correlate with server logs.

Parallel and intercepting routes (modal pattern)

app/
  layout.tsx            // renders {children} and {modal}
  @modal/
    default.tsx         // export default () => null
    (.)photos/[id]/page.tsx   // modal when navigating from within the app
  photos/[id]/page.tsx  // full page on direct load or refresh

• The layout receives each slot as a prop: { children, modal }.
• Close the modal with router.back(). Add a catch-all @modal/[...catchAll]/page.tsx returning null if other navigations should dismiss it.
• Without default.tsx, a hard refresh on an unrelated URL 404s (and Next 16 fails the build).

Route handlers

// app/api/projects/[id]/route.ts
import { NextResponse, type NextRequest } from "next/server";

export async function GET(_req: NextRequest, ctx: RouteContext<"/api/projects/[id]">) {
  const { id } = await ctx.params;
  const project = await findProject(id);
  if (!project) return NextResponse.json({ error: "Not found" }, { status: 404 });
  return NextResponse.json(project);
}

• GET handlers are not cached by default since Next 15.
• Authenticate inside the handler. Do not rely on proxy.ts/middleware.ts alone for authorization: matchers drift and it is a single point of bypass.
• Prefer server actions for mutations triggered by your own UI; use route handlers for webhooks, third-party callers, file downloads and non-React clients.

Navigation

• <Link> prefetches in production when visible. For a big list of links, set prefetch={false} on low-value ones to limit requests.
• useRouter, usePathname, useSearchParams, useParams come from next/navigation. Wrap components that call useSearchParams in <Suspense>; on a statically rendered page the build otherwise fails with a missing-Suspense client-rendering bailout error.
• Use redirect() in server code; router.push() only in client event handlers.

Gotchas

• searchParams makes a page dynamic. Read it only in the components that need it.
• A route.ts and page.tsx in the same folder is a build error.
• Route groups with different root layouts cause a full page load when navigating between them.
• generateStaticParams in a layout applies to all child pages; a forgotten one causes unexpected build-time fetching.
• Mixing src/app and app at the root: Next uses app and ignores src/app.

Verification

• next build passes. Read the route table it prints and confirm each route’s rendering mode (static, dynamic, partial) matches intent.
• Visit each new URL directly (hard load) and via client navigation.
• Force an error (throw in the page) and a missing record to see error.tsx and not-found.tsx render at the right level, then remove the test throw.
• Throttle network and confirm loading UI appears where expected.
• For modals: open from the list, refresh on the modal URL, use the back button.

Output

Report the folder tree you added or changed, which segments got loading/error boundaries and why, and the rendering mode of each touched route from the build output.