Skip to content
Getting StartedProject Structure

Next.js Project Structure

This page provides an overview of the file and folder structure of a Next.js project. It covers top-level files and folders, configuration files, and routing conventions within the app and pages directories.

Top-level folders

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

Top-level files

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

app Routing Conventions

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


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

pages Routing Conventions

Special Files

_app.js .jsx .tsxCustom App
_document.js .jsx .tsxCustom Document
_error.js .jsx .tsxCustom Error Page
404.js .jsx .tsx404 Error Page
500.js .jsx .tsx500 Error Page


Folder convention
index.js .jsx .tsxHome page
folder/index.js .jsx .tsxNested page
File convention
index.js .jsx .tsxHome page
file.js .jsx .tsxNested page

Dynamic Routes

Folder convention
[folder]/index.js .jsx .tsxDynamic route segment
[...folder]/index.js .jsx .tsxCatch-all route segment
[[...folder]]/index.js .jsx .tsxOptional catch-all route segment
File convention
[file].js .jsx .tsxDynamic route segment
[...file].js .jsx .tsxCatch-all route segment
[[...file]].js .jsx .tsxOptional catch-all route segment