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.txtKeeping 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 callnotFound().route.ts: an API endpoint with functions likeGETandPOST; it cannot sit next to apage.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
- One module talks to your backend (for example
lib/api.ts); pages never callfetchwith raw URLs. - Content and copy live in data files, not inside components, so editing text never touches layout code.
- Use the
@/import alias instead of long relative paths like../../../. - Delete unused files right away; dead code is what makes structure rot.