Skip to content
App RouterGetting StartedProject Structure

Project structure and organization

This page provides an overview of the folder and file conventions in Next.js, as well as tips for organizing your project.

Folder and file conventions

Top-level folders

Top-level folders are used to organize your application's code and static assets.

Route segments to path segments
appApp Router
pagesPages Router
publicStatic assets to be served
srcOptional application source folder

Top-level files

Top-level files are used to configure your application, manage dependencies, run middleware, integrate monitoring tools, and define environment variables.

Next.js
next.config.jsConfiguration file for Next.js
package.jsonProject dependencies and scripts
instrumentation.tsOpenTelemetry and Instrumentation file
middleware.tsNext.js request middleware
.envEnvironment variables
.env.localLocal environment variables
.env.productionProduction environment variables
.env.developmentDevelopment environment variables
.eslintrc.jsonConfiguration 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

Routing Files

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

folderRoute segment
folder/folderNested route segment

Dynamic routes

[folder]Dynamic route segment
[...folder]Catch-all route segment
[[...folder]]Optional catch-all route segment

Route Groups and private folders

(folder)Group routes without affecting routing
_folderOpt folder and all child segments out of routing

Parallel and Intercepted Routes

@folderNamed slot
(.)folderIntercept same level
(..)folderIntercept one level above
(..)(..)folderIntercept two levels above
(...)folderIntercept from root

Metadata file conventions

App icons

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

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

sitemap.xmlSitemap file
sitemap.js .tsGenerated Sitemap
robots.txtRobots file
robots.js .tsGenerated Robots file

Organizing your project

Apart from folder and file conventions, Next.js is unopinionated about how you organize and colocate your project files. But it does provide several features to help you organize your project.

Colocation

In the app directory, nested folder hierarchy defines route structure. Each folder represents a route segment that is mapped to a corresponding segment in a URL path.

However, even though route structure is defined through folders, a route is not publicly accessible until a page.js or route.js file is added to a route segment.

A diagram showing how a route is not publicly accessible until a page.js or route.js file is added to a route segment.

And, even when a route is made publicly accessible, only the content returned by page.js or route.js is sent to the client.

A diagram showing how page.js and route.js files make routes publicly accessible.

This means that project files can be safely colocated inside route segments in the app directory without accidentally being routable.

A diagram showing colocated project files are not routable even when a segment contains a page.js or route.js file.

Good to know:

Private folders

Private folders can be created by prefixing a folder with an underscore: _folderName

This indicates the folder is a private implementation detail and should not be considered by the routing system, thereby opting the folder and all its subfolders out of routing.

An example folder structure using private folders

Since files in the app directory can be safely colocated by default, private folders are not required for colocation. However, they can be useful for:

  • Separating UI logic from routing logic.
  • Consistently organizing internal files across a project and the Next.js ecosystem.
  • Sorting and grouping files in code editors.
  • Avoiding potential naming conflicts with future Next.js file conventions.

Good to know:

  • While not a framework convention, you might also consider marking files outside private folders as "private" using the same underscore pattern.
  • You can create URL segments that start with an underscore by prefixing the folder name with %5F (the URL-encoded form of an underscore): %5FfolderName.
  • If you don't use private folders, it would be helpful to know Next.js special file conventions to prevent unexpected naming conflicts.

Route groups

Route groups can be created by wrapping a folder in parenthesis: (folderName)

This indicates the folder is for organizational purposes and should not be included in the route's URL path.

An example folder structure using route groups

Route groups are useful for:

src directory

Next.js supports storing application code (including app) inside an optional src directory. This separates application code from project configuration files which mostly live in the root of a project.

An example folder structure with the `src` directory

Common strategies

The following section lists a very high-level overview of common strategies. The simplest takeaway is to choose a strategy that works for you and your team and be consistent across the project.

Good to know: In our examples below, we're using components and lib folders as generalized placeholders, their naming has no special framework significance and your projects might use other folders like ui, utils, hooks, styles, etc.

Store project files outside of app

This strategy stores all application code in shared folders in the root of your project and keeps the app directory purely for routing purposes.

An example folder structure with project files outside of app

Store project files in top-level folders inside of app

This strategy stores all application code in shared folders in the root of the app directory.

An example folder structure with project files inside app

Split project files by feature or route

This strategy stores globally shared application code in the root app directory and splits more specific application code into the route segments that use them.

An example folder structure with project files split by feature or route