UndieGravity LogoUndiegravity

How to Structure a Next.js App Router Project

A clean Next.js App Router folder structure: what goes in app, route groups and private folders, special files, and where to put components and helpers.

By UndieGravity, , 2 min read

A Next.js project stays easy to change when you can guess where any file lives. The App Router gives you a few hard rules; the rest is convention. Here is a structure that scales from a landing page to a full product.

The shape of the project

app/            routes only: pages, layouts, route handlers
  (marketing)/  route group: shares a layout, not part of the URL
  blog/[slug]/  dynamic route
  api/          route handlers (route.ts)
features/       code for one feature: blog, checkout, dashboard
ui/             generic building blocks: Button, Input, Card
lib/            helpers with no UI: api client, formatting, types
public/         files served as is: icons, robots extras, llms.txt

Keeping app/ for routing means a quick look at the folder tree shows every URL in the site.

Special files inside a route folder

  • page.tsx: makes the folder a public URL.
  • layout.tsx: wraps the page and all child routes; it stays mounted while users navigate.
  • loading.tsx: shown instantly while the page loads, using Suspense.
  • error.tsx: catches errors in the segment and shows a fallback with a retry button.
  • not-found.tsx: shown when you call notFound().
  • route.ts: an API endpoint with functions like GET and POST; it cannot sit next to a page.tsx.

Route groups and private folders

Wrap a folder name in parentheses, such as (legal), to group routes under a shared layout without changing the URL: app/(legal)/privacy/page.tsx is served at /privacy. Prefix a folder with an underscore, such as _lib, to keep it out of routing completely.

Dynamic segments

  • [slug] matches one segment: /blog/hello.
  • [...slug] matches one or more: /docs/a/b/c.
  • [[...slug]] also matches the parent with no segment: /docs.

Add generateStaticParams to prerender every known slug at build time, and export const dynamicParams = false to return a 404 for anything else.

Features over file types

Group code by what it does, not by what it is. A features/blog/ folder with its card, list, and helpers is easier to work on than a components/ folder with hundreds of unrelated files. Move a component to ui/ only when two features need it.

Rules that keep it clean

  1. One module talks to your backend (for example lib/api.ts); pages never call fetch with raw URLs.
  2. Content and copy live in data files, not inside components, so editing text never touches layout code.
  3. Use the @/ import alias instead of long relative paths like ../../../.
  4. Delete unused files right away; dead code is what makes structure rot.

Keep reading

Next.js

Next.js 16: What Changed and How to Upgrade

Next.js 16 makes Turbopack the default, renames middleware to proxy, requires async request APIs, and changes caching. Here is what to update first.

, 2 min read