Skip to main content

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.

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

app Routing Conventions​

The following file conventions are used to define routes and handle metadata in the app router.

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

pages Routing Conventions​

The following file conventions are used to define routes in the pages router.

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

Routes​

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