Next.js App Router

Next.js App Router

Structure Next.js 13+ applications using the App Router's file-system conventions for layouts, nested routes, and route segments

When to Use

• Starting a new Next.js project with version 13 or later
• Migrating from the Pages Router to the App Router
• Adding nested layouts, route groups, or parallel routes
• Designing URL structures that share UI across multiple routes
• Working with app/ directory conventions (layout.tsx, page.tsx, loading.tsx, error.tsx)

Instructions

1. Place all routes under app/. Each folder becomes a route segment; page.tsx makes it publicly accessible.
2. Use layout.tsx to wrap route segments in shared UI — layouts persist across navigations and do not re-render.
3. Create route groups with (groupName)/ to organize routes without affecting the URL path.
4. Use [slug] for dynamic segments and [...catchAll] for catch-all segments. Access params via the params prop in page.tsx and layout.tsx.
5. Co-locate loading.tsx alongside page.tsx to stream a Suspense fallback during data fetching.
6. Co-locate error.tsx as a Client Component to catch runtime errors within the segment.
7. Use not-found.tsx to render 404 UI and call notFound() from next/navigation to trigger it.
8. Use template.tsx instead of layout.tsx when you need fresh state on every navigation (e.g., page-transition animations).
9. Prefer route groups to share layouts across unrelated URL paths without creating a shared parent segment.
10. Keep layout.tsx Server Components by default; only add 'use client' if the layout needs interactivity.

// app/dashboard/layout.tsx — shared layout for all /dashboard/* routes
export default function DashboardLayout({ children }: { children: React.ReactNode }) {
  return (
    <div className="flex">
      <DashboardNav />
      <main className="flex-1">{children}</main>
    </div>
  );
}

// app/dashboard/[teamId]/page.tsx — dynamic route segment
export default function TeamPage({ params }: { params: { teamId: string } }) {
  return <h1>Team {params.teamId}</h1>;
}

Details

The App Router replaces the Pages Router's getServerSideProps / getStaticProps model with React Server Components and async components. Every file in app/ is a Server Component by default.

File conventions: page.tsx (route UI), layout.tsx (shared wrapper), loading.tsx (Suspense fallback), error.tsx (error boundary), not-found.tsx (404), route.ts (API endpoint), template.tsx (per-navigation layout), default.tsx (parallel route fallback).

Route groups (groupName)/ exist only in the filesystem — they do not appear in the URL. Use them to co-locate files without coupling the URL structure.

Trade-offs:

• Layouts cannot read search params — use searchParams prop in page.tsx instead
• layout.tsx is not re-mounted on navigation within its segment, so component state persists; use template.tsx if fresh state is needed
• Deeply nested layouts increase the React component tree depth — profile rendering if performance degrades

Migration from Pages Router: Pages under pages/ continue to work alongside app/ — the two routers coexist during migration. Remove a page from pages/ only after its app/ equivalent is tested.

Source

https://nextjs.org/docs/app/building-your-application/routing

Process

1. Read the instructions and examples in this document.
2. Apply the patterns to your implementation, adapting to your specific context.
3. Verify your implementation against the details and edge cases listed above.

Harness Integration

• Type: knowledge — this skill is a reference document, not a procedural workflow.
• No tools or state — consumed as context by other skills and agents.

Success Criteria

• The patterns described in this document are applied correctly in the implementation.
• Edge cases and anti-patterns listed in this document are avoided.