Next.js Project Structure
This page provides an overview of the project structure of a Next.js application. It covers top-level files and folders, configuration files, and routing conventions within the app and pages directories.
Click the file and folder names to learn more about each convention.
Top-level folders
Top-level folders are used to organize your application's code and static assets.
app | App Router |
pages | Pages Router |
public | Static assets to be served |
src | Optional 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.js | Configuration file for Next.js |
package.json | Project dependencies and scripts |
instrumentation.ts | OpenTelemetry and Instrumentation file |
middleware.ts | Next.js request middleware |
.env | Environment variables |
.env.local | Local environment variables |
.env.production | Production environment variables |
.env.development | Development environment variables |
.eslintrc.json | Configuration file for ESLint |
.gitignore | Git files and folders to ignore |
next-env.d.ts | TypeScript declaration file for Next.js |
tsconfig.json | Configuration file for TypeScript |
jsconfig.json | Configuration file for JavaScript |
app Routing Conventions
The following file conventions are used to define routes and handle metadata in the app router.
Routing Files
layout | .js .jsx .tsx | Layout |
page | .js .jsx .tsx | Page |
loading | .js .jsx .tsx | Loading UI |
not-found | .js .jsx .tsx | Not found UI |
error | .js .jsx .tsx | Error UI |
global-error | .js .jsx .tsx | Global error UI |
route | .js .ts | API endpoint |
template | .js .jsx .tsx | Re-rendered layout |
default | .js .jsx .tsx | Parallel route fallback page |
Nested Routes
folder | Route segment |
folder/folder | Nested 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 |
_folder | Opt folder and all child segments out of routing |
Parallel and Intercepted Routes
@folder | Named slot |
(.)folder | Intercept same level |
(..)folder | Intercept one level above |
(..)(..)folder | Intercept two levels above |
(...)folder | Intercept from root |
Metadata File Conventions
App Icons
favicon | .ico | Favicon file |
icon | .ico .jpg .jpeg .png .svg | App Icon file |
icon | .js .ts .tsx | Generated App Icon |
apple-icon | .jpg .jpeg, .png | Apple App Icon file |
apple-icon | .js .ts .tsx | Generated Apple App Icon |
Open Graph and Twitter Images
opengraph-image | .jpg .jpeg .png .gif | Open Graph image file |
opengraph-image | .js .ts .tsx | Generated Open Graph image |
twitter-image | .jpg .jpeg .png .gif | Twitter image file |
twitter-image | .js .ts .tsx | Generated Twitter image |
SEO
sitemap | .xml | Sitemap file |
sitemap | .js .ts | Generated Sitemap |
robots | .txt | Robots file |
robots | .js .ts | Generated Robots file |
pages Routing Conventions
The following file conventions are used to define routes in the pages router.
Special Files
_app | .js .jsx .tsx | Custom App |
_document | .js .jsx .tsx | Custom Document |
_error | .js .jsx .tsx | Custom Error Page |
404 | .js .jsx .tsx | 404 Error Page |
500 | .js .jsx .tsx | 500 Error Page |
Routes
| Folder convention | ||
index | .js .jsx .tsx | Home page |
folder/index | .js .jsx .tsx | Nested page |
| File convention | ||
index | .js .jsx .tsx | Home page |
file | .js .jsx .tsx | Nested page |
Dynamic Routes
| Folder convention | ||
[folder]/index | .js .jsx .tsx | Dynamic route segment |
[...folder]/index | .js .jsx .tsx | Catch-all route segment |
[[...folder]]/index | .js .jsx .tsx | Optional catch-all route segment |
| File convention | ||
[file] | .js .jsx .tsx | Dynamic route segment |
[...file] | .js .jsx .tsx | Catch-all route segment |
[[...file]] | .js .jsx .tsx | Optional catch-all route segment |