Next.js Folder Structure: App Router Layout Explained
November 11, 2026 · 13 min read
Next.js Folder Structure: The App Router Project Layout Explained
A Next.js folder structure has only four top-level folders the framework treats specially. They're app/ for App Router routes, pages/ for the older Pages Router, public/ for static files and an optional src/. Everything else, from components/ to lib/, is your call. Below is an annotated tree you can copy, plus where your own code and Markdown belong.
What a Fresh create-next-app Project Contains
Run npx create-next-app@latest my-app --yes on a machine with no saved preferences and you get the recommended defaults. Per the installation docs, that means TypeScript, ESLint, Tailwind CSS, the App Router, Turbopack, the @/* import alias and an AGENTS.md file, with no src/ folder. Here's the tree it generates in Next.js 16, the current major version as of November 2026:
my-app/
├── app/
│ ├── favicon.ico # browser tab icon (a metadata file convention)
│ ├── globals.css # global styles, imported by the root layout
│ ├── layout.tsx # root layout: wraps every page, holds <html> and <body>
│ └── page.tsx # the home page, served at /
├── public/ # static files served from / (file.svg, next.svg and more)
├── .env.example # sample variables, rename to .env.local to use them
├── .gitignore
├── AGENTS.md # instructions for AI coding agents
├── README.md
├── eslint.config.mjs # ESLint flat config
├── next-env.d.ts # Next.js types for TypeScript, keep it out of Git
├── next.config.ts # Next.js configuration
├── package.json # dependencies and scripts
├── postcss.config.mjs # loads the Tailwind CSS PostCSS plugin
└── tsconfig.json # TypeScript settings, including the @/* alias
After the install you'll also have node_modules/ and a lock file. Customize the prompts and the list changes: picking Biome gives you biome.json instead of the ESLint config, and picking JavaScript gives you .js files and a jsconfig.json.
Two more root files appear only when you add them. proxy.ts intercepts requests; Next.js 16.0.0 deprecated middleware.ts and renamed the convention to proxy. instrumentation.ts hooks in OpenTelemetry and monitoring tools. Your .env, .env.local, .env.development and .env.production files also sit at the root, and the docs say none of them should be committed.
Here's what Next.js does with each special top-level folder:
| Folder | What Next.js does with it |
|---|---|
app/ | App Router: nested folders become URL segments |
pages/ | Pages Router: the older file-based router |
public/ | Static assets, served from the site root |
src/ | Optional wrapper that holds app/ or pages/ |
So public/avatars/me.png is served at /avatars/me.png. create-next-app labels the App Router as recommended, and the rest of this guide assumes it.
The Special Files Inside app/: page, layout, loading and error
Folders in app/ define routes, and a handful of reserved file names define what each route renders. The project structure docs list nine:
| File | Role |
|---|---|
page.tsx | The UI for a route; makes the folder publicly reachable |
layout.tsx | Shared UI such as a header or nav that wraps child routes |
template.tsx | Like a layout, but re-rendered on navigation |
loading.tsx | Loading skeleton, wrapped in a Suspense boundary |
error.tsx | Error boundary for the segment |
global-error.tsx | Error UI for the whole app |
not-found.tsx | UI for not found responses |
route.ts | An API endpoint instead of a page |
default.tsx | Fallback page for a parallel route slot |
The root layout is the one file every App Router project needs. It must render the <html> and <body> tags, and every page appears where children sits:
import './globals.css'
export default function RootLayout({ children }: { children: React.ReactNode }) {
return (
<html lang="en">
<body>{children}</body>
</html>
)
}
Inside one folder, Next.js nests these in a fixed order: layout, then template, error, loading, not-found, and finally the page. Child segments render inside their parent's components.
Two rules make colocation safe. A folder isn't a public route until it contains page.tsx or route.ts. And even then, only what those two files return is sent to the browser, so a utils.ts or Button.tsx next to a page never becomes a URL.
How Folder Names Turn Into URLs
This table maps every folder naming pattern to the URL it produces. Bookmark it, because the brackets and parentheses are easy to mix up.
| Path in app/ | URL | Why |
|---|---|---|
app/page.tsx | / | Root page |
app/blog/page.tsx | /blog | Each folder adds a segment |
app/blog/[slug]/page.tsx | /blog/my-first-post | Dynamic segment, one value |
app/shop/[...slug]/page.tsx | /shop/clothing/shirts | Catch-all, one or more segments |
app/docs/[[...slug]]/page.tsx | /docs or /docs/a/b | Optional catch-all, also matches /docs |
app/(marketing)/about/page.tsx | /about | Route group, left out of the URL |
app/blog/_components/Post.tsx | none | Private folder, never routed |
app/dashboard/@sidebar/page.tsx | /dashboard | Named slot passed to the parent layout |
Two edge cases trip people up. If you need a real URL that starts with an underscore, name the folder %5Fname, the URL-encoded underscore. And intercepting routes such as (.)photo are typically used to show a route in a modal over the current page.
Should You Use a src Folder in Next.js?
A src/ folder moves your application code away from the config files at the root. To use it, move app/ to src/app/ and bring your other code folders with it:
my-app/
├── public/ # stays at the root
├── src/
│ ├── app/
│ ├── components/
│ ├── lib/
│ └── proxy.ts # same level as app/
├── .env.local # stays at the root
├── next.config.ts # stays at the root
├── package.json
└── tsconfig.json # update the @/* path to point into src/
The src folder docs set the rules. public/, config files and .env.* files stay at the root. If both app/ and src/app/ exist, Next.js ignores src/app/. proxy.ts moves inside src/, and TypeScript paths such as @/* need the src/ prefix. In tsconfig.json, that entry ends up like this:
"paths": {
"@/*": ["./src/*"]
}
With that in place, import Button from '@/components/ui/Button' resolves to src/components/ui/Button.tsx. Restart the dev server after moving folders so it picks up the new locations.
create-next-app's recommended defaults skip src/, and that's fine for a small site. We prefer src/ once a project has more than two or three code folders, because config files and code stop interleaving in your file list. Python has the same choice, and our Python project structure guide compares its flat and src layouts.
Where Do Components, Hooks and lib Code Go?
Next.js doesn't care. The docs say names like components and lib have no special framework significance, and they describe three strategies for your Next.js project structure:
- Outside app/:
app/holds routing only, and shared code lives in root folders such ascomponents/andlib/. - Top-level folders inside app/: shared code goes in
app/_components/andapp/_lib/. - Split by feature or route: global code sits at the top, and route-specific code moves into the segment that uses it, such as
app/blog/_components/.
The docs don't rank them. In our experience, the right one depends mostly on project size:
| Project | Strategy that holds up |
|---|---|
| A few routes, one developer | Outside app/, with flat components/ and lib/ |
| A product with 10 to 50 routes | Outside app/ for shared code, plus private _components/ per route |
| Several teams or domains | features/ folders per domain, plus route groups |
The common folders each do one job. components/ui/ holds primitives like buttons and inputs, and components/ holds composed pieces like a site header. hooks/ holds custom React hooks, and any hook that uses state or effects needs a Client Component. lib/ holds data fetching, database clients and small utilities, and types/ holds shared TypeScript types. Whatever you choose, the docs' advice is the useful part: pick one approach and stay consistent.
A feature folder groups everything one domain needs, so a page file stays thin:
features/billing/
├── components/
│ ├── InvoiceTable.tsx
│ └── PlanPicker.tsx
├── actions.ts # Server Actions for billing
├── index.ts # what the rest of the app imports
├── queries.ts # data fetching for billing
└── types.ts
A route such as app/(shop)/billing/page.tsx imports from @/features/billing, which resolves to that index.ts, and renders the result. When the business drops a feature, you delete one folder instead of hunting through components/ and lib/.
Organizing Large Apps With Route Groups and Private Folders
Route groups let you split a big app/ by section or team without touching URLs. Here's a mid-size layout that uses them, with features kept outside app/:
src/
├── app/
│ ├── layout.tsx # root layout for every route
│ ├── (marketing)/
│ │ ├── layout.tsx # marketing header and footer
│ │ ├── page.tsx # /
│ │ └── pricing/page.tsx # /pricing
│ ├── (shop)/
│ │ ├── layout.tsx # shop navigation
│ │ ├── cart/page.tsx # /cart
│ │ └── products/[id]/page.tsx
│ └── dashboard/
│ ├── (overview)/
│ │ ├── loading.tsx # skeleton for /dashboard only
│ │ └── page.tsx # /dashboard
│ ├── settings/page.tsx # /dashboard/settings
│ └── _components/ # dashboard-only UI, not routable
├── components/ui/
├── features/
│ ├── billing/
│ └── catalog/
└── lib/
Each group's layout.tsx nests inside the root layout, so marketing and shop pages get different chrome. The (overview) group scopes loading.tsx to the dashboard index without also covering /dashboard/settings.
For completely different shells, delete app/layout.tsx and give each group its own root layout. Every root layout then needs its own <html> and <body> tags, and moving between them triggers a full page load. Also watch for collisions: (marketing)/about and (shop)/about both resolve to /about, which Next.js reports as an error.
Private folders like _components/ aren't required for colocation, since non-page files are never routed anyway. The docs still list good reasons to use them. They separate UI logic from routing, keep internal files organized the same way across a project, sort related files together in your editor, and avoid clashes with special file names Next.js might add later.
Where Markdown and MDX Content Lives in a Next.js Project
The official MDX guide shows two places for content. You can write a route directly as page.mdx inside app/, or keep posts in a separate folder and import them from a dynamic route:
my-app/
├── app/
│ ├── about/
│ │ └── page.mdx # /about, written in MDX
│ └── blog/
│ └── [slug]/
│ └── page.tsx # loads content/<slug>.mdx
├── content/
│ ├── hello-world.mdx
│ └── nextjs-tips.mdx
├── mdx-components.tsx # required for @next/mdx with the App Router
└── next.config.ts # pageExtensions adds md and mdx
The blog route imports the matching file by slug:
export default async function Page({ params }: { params: Promise<{ slug: string }> }) {
const { slug } = await params
const { default: Post } = await import(`@/content/${slug}.mdx`)
return <Post />
}
export function generateStaticParams() {
return [{ slug: 'hello-world' }, { slug: 'nextjs-tips' }]
}
export const dynamicParams = false
Visiting /blog/hello-world renders content/hello-world.mdx. generateStaticParams prerenders the listed slugs, and dynamicParams = false turns any other slug into a 404. We prefer the content/ folder over page.mdx files, because writers never have to open a routing folder. It also makes a blog index easy: read the folder with Node's fs module at build time and list every post.
mdx-components.tsx sits at the root next to app/, or inside src/ if you use one. Without it, @next/mdx won't work with the App Router. @next/mdx also doesn't support frontmatter by default; our MDX Markdown guide covers that and the rest of the syntax. If your Markdown arrives as a string at runtime, render it with react-markdown. For a standalone docs/ folder, see how to write documentation in Markdown.
Documenting Your Next.js Folder Structure in a README
Once the layout settles, write it down. A README section with a tree and a path-to-URL table saves every new teammate a guided tour. Our directory tree generator draws the tree from an indented list or a list of paths. It can also read the file paths of a folder you pick, inside your browser with nothing uploaded, and outputs box-drawing, ASCII or Markdown-list text. It only draws a diagram, so it won't scaffold a Next.js app for you. If you'd rather stay in the terminal, our Linux directory tree guide shows how to print one with the tree command.
The table half is plain Markdown. Try it here:
The preview on the right renders the table and the list. Edit the rows to match your repo, then copy the Markdown into your README. One limitation: our preview treats a pasted MDX file as plain Markdown. Import lines show up as ordinary text, JSX components don't run and front matter isn't rendered, so check those in your Next.js dev server.
Next.js Folder Structure Questions
A good Next.js folder structure keeps routing in app/, static files in public/, config at the root and your own code in a few clearly named folders. Start with the create-next-app defaults, add src/ and route groups as the app grows, and keep Markdown content in its own folder. When you document the layout, draft the README table in the editor and check the preview before you commit.