Skip to main content
This page provides an overview of all the folder and file conventions in Next.js, and recommendations for organizing your project.

​
Top-level folders

Top-level folders are used to organize your application’s code and static assets.
FolderDescription
appApp Router
pagesPages Router (legacy)
publicStatic assets to be served
srcOptional application source folder

​
Top-level files

Top-level files configure your application, manage dependencies, define environment variables, and integrate tooling.
FileDescription
next.config.jsConfiguration file for Next.js
package.jsonProject dependencies and scripts
instrumentation.tsOpenTelemetry and instrumentation file
proxy.tsNext.js request proxy
.envEnvironment variables
.env.localLocal environment variables
.env.productionProduction environment variables
.env.developmentDevelopment environment variables
eslint.config.mjsConfiguration file for ESLint
.gitignoreGit files and folders to ignore
next-env.d.tsTypeScript declaration file for Next.js
tsconfig.jsonConfiguration file for TypeScript
jsconfig.jsonConfiguration file for JavaScript
.env, .env.local, .env.production, and .env.development should not be tracked by version control. Add them to .gitignore.

​
Routing files

Add page to expose a route, layout for shared UI, loading for skeletons, error for error boundaries, and route for API endpoints.
FileExtensionsDescription
layout.js .jsx .tsxLayout
page.js .jsx .tsxPage
loading.js .jsx .tsxLoading UI
not-found.js .jsx .tsxNot found UI
error.js .jsx .tsxError UI
global-error.js .jsx .tsxGlobal error UI
route.js .tsAPI endpoint
template.js .jsx .tsxRe-rendered layout
default.js .jsx .tsxParallel route fallback page

​
Nested routes

Folders define URL segments. Nesting folders nests segments. Layouts at any level wrap their child segments. A route becomes publicly accessible when a page or route file exists in a segment.
PathURL patternNotes
app/layout.tsx—Root layout, wraps all routes
app/blog/layout.tsx—Wraps /blog and descendants
app/page.tsx/Public route
app/blog/page.tsx/blogPublic route
app/blog/authors/page.tsx/blog/authorsPublic route

​
Dynamic routes

Parameterize segments with square brackets. Use [segment] for a single param, [...segment] for catch-all, and [[...segment]] for optional catch-all. Access values via the params prop.
PathURL pattern
app/blog/[slug]/page.tsx/blog/my-first-post
app/shop/[...slug]/page.tsx/shop/clothing, /shop/clothing/shirts
app/docs/[[...slug]]/page.tsx/docs, /docs/layouts-and-pages

​
Route groups and private folders

Organize code without changing URLs with route groups (group), and colocate non-routable files with private folders _folder.
PathURL patternNotes
app/(marketing)/page.tsx/Group omitted from URL
app/(shop)/cart/page.tsx/cartShare layouts within (shop)
app/blog/_components/Post.tsx—Not routable; safe place for UI utilities
app/blog/_lib/data.ts—Not routable; safe place for utils

​
Metadata file conventions

​
App icons

FileExtensionsDescription
favicon.icoFavicon file
icon.ico .jpg .jpeg .png .svgApp icon file
icon.js .ts .tsxGenerated app icon
apple-icon.jpg .jpeg .pngApple app icon file
apple-icon.js .ts .tsxGenerated Apple app icon

​
Open Graph and Twitter images

FileExtensionsDescription
opengraph-image.jpg .jpeg .png .gifOpen Graph image file
opengraph-image.js .ts .tsxGenerated Open Graph image
twitter-image.jpg .jpeg .png .gifTwitter image file
twitter-image.js .ts .tsxGenerated Twitter image

​
SEO

FileExtensionsDescription
sitemap.xmlSitemap file
sitemap.js .tsGenerated sitemap
robots.txtRobots file
robots.js .tsGenerated robots file

​
Component hierarchy

The components defined in special files are rendered in a specific hierarchy within each route segment:
  1. layout.js
  2. template.js
  3. error.js (React error boundary)
  4. loading.js (React suspense boundary)
  5. not-found.js (React error boundary for not-found UI)
  6. page.js or nested layout.js
Components are rendered recursively in nested routes, meaning the components of a route segment are nested inside the components of its parent segment.

​
Organizing your project

Next.js is unopinionated about how you organize and colocate your project files. It provides several features to help.

​
Colocation

In the app directory, nested folders define route structure. However, a route is not publicly accessible until a page.js or route.js file is added. This means project files can be safely colocated inside route segments without accidentally becoming routable.

​
Private folders

Prefix a folder with an underscore to mark it as a private implementation detail: _folderName This opts the folder and all its subfolders out of routing. Useful for:
  • Separating UI logic from routing logic.
  • Organizing internal files consistently across a project.
  • Avoiding naming conflicts with future Next.js file conventions.
You can create URL segments that start with an underscore by prefixing the folder name with %5F (the URL-encoded underscore): %5FfolderName.

​
Route groups

Wrap a folder in parentheses to create a route group: (folderName) The folder name is omitted from the URL path and is used only for organizational purposes. Route groups are useful for:
  • Organizing routes by site section, intent, or team (e.g. marketing pages, admin pages).
  • Enabling nested layouts in the same route segment level.
  • Creating multiple root layouts.

​
src folder

Next.js supports storing application code (including app) inside an optional src folder. This separates application code from project configuration files that live in the root.

​
Project organization strategies

Choose a strategy that works for your team and apply it consistently.
Store all application code in shared folders at the root of your project and keep the app directory purely for routing.
├── app/
│   ├── layout.tsx
│   └── page.tsx
├── components/
│   └── button.tsx
├── lib/
│   └── utils.ts
└── styles/
    └── globals.css
Store all application code in shared folders at the root of the app directory.
├── app/
│   ├── layout.tsx
│   ├── page.tsx
│   ├── components/
│   │   └── button.tsx
│   └── lib/
│       └── utils.ts
Store globally shared code in the root app directory and split more specific code into the route segments that use it.
├── app/
│   ├── layout.tsx
│   ├── page.tsx
│   ├── components/       # shared
│   └── dashboard/
│       ├── page.tsx
│       └── components/   # dashboard-specific

​
Organizing routes without affecting URLs

To group related routes without changing the URL, use route groups. Folders in parentheses are omitted from the URL: 
app/
├── (marketing)/
│   ├── layout.tsx    # marketing layout
│   ├── page.tsx      # /
│   └── about/
│       └── page.tsx  # /about
└── (shop)/
    ├── layout.tsx    # shop layout
    └── cart/
        └── page.tsx  # /cart
Even though routes inside (marketing) and (shop) share the same URL hierarchy, each group can have its own layout.js.

​
Creating multiple root layouts

To create multiple root layouts, remove the top-level layout.js file and add a layout.js inside each route group. Each root layout must include <html> and <body> tags. 
app/
├── (marketing)/
│   └── layout.tsx  # root layout for marketing
└── (shop)/
    └── layout.tsx  # root layout for shop

Build docs developers (and LLMs) love

Get started for freeTalk to us