Getting Started with the Next.js App Router

This is a reference-style guide to the core conventions of the Next.js App Router.

File conventions

Nested layouts

Layouts nest automatically based on folder structure. A layout.tsx in app/blog/ wraps every route under /blog, in addition to the root layout.

Static params for dynamic routes

For a fully static export, every dynamic segment needs generateStaticParams so Next.js knows every path to pre-render at build time.

export async function generateStaticParams() {
  const posts = getAllPosts();
  return posts.map((post) => ({ slug: post.slug }));
}

Metadata

Each route can export a generateMetadata function to produce per-page <title>, description, and Open Graph tags at build time.

export async function generateMetadata({ params }) {
  const { slug } = await params;
  const post = getPostBySlug(slug);
  return { title: post.title, description: post.description };
}

Server vs. Client Components

By default, every component in app/ is a Server Component. Add "use client" at the top of a file only when you need interactivity, browser APIs, or React hooks like useState.

Route groups and parallel routes

Two less obvious file conventions worth knowing once the basics above feel routine:

Parentheses around a folder name ((marketing)) create a route group — it organizes routes and can carry its own layout without adding a segment to the actual URL. This is the tool for giving a marketing site section and an authenticated app section entirely different layouts while both living under the same app/ tree.

Parallel and intercepting routes (the @modal and (.) conventions) let a route render as a modal overlay when navigated to from within the app, while still rendering as a full standalone page on a direct URL visit or refresh — the pattern behind "click a photo thumbnail, it opens as a modal, but the modal's URL is also a real, shareable, fully-rendered page."

Loading and error boundaries are scoped per segment

loading.tsx and error.tsx aren't global — each one only wraps the segment (and its children) where it's placed, which means different parts of a route tree can have independent loading and error states instead of one blanket spinner or error page for the whole app:

A nested loading.tsx takes priority over a parent's for its own subtree, letting a slow-loading nested section show its own loading state without blanking out the rest of an already-rendered page around it.

Colocating non-route files safely

Any file inside app/ that isn't one of the special names above (_components/, _utils/, or a leading-underscore folder) is safe to colocate next to the routes that use it, without becoming a route itself:

The underscore prefix explicitly opts a folder out of routing, which is the cleanest way to keep a route's helper components physically close to where they're used instead of pushed into a distant shared components/ directory purely to avoid accidentally creating a route.

Common mistakes

Troubleshooting

Related reading

• Next.js Middleware: What It's For and When to Avoid It — shares tags: nextjs, react, web-development (same category).
• React Server Components Explained: What They Are and When to Use Them — shares tags: react, nextjs, web-development.
• React useEffect Cleanup: A Practical Guide — shares tags: react, web-development.
• Core Web Vitals Explained: What Actually Affects Your Score — shares tags: web-development.
• The JavaScript Event Loop, Explained With Diagrams — shares tags: web-development.