971a1a6421
Closes: - https://github.com/vercel/feedback/issues/54964 - https://github.com/vercel/feedback/issues/54580 - https://github.com/vercel/feedback/issues/54555 - https://github.com/vercel/feedback/issues/54341 - https://github.com/vercel/feedback/issues/54309 - https://github.com/vercel/feedback/issues/53751 - https://github.com/vercel/feedback/issues/55173 Add diagram: https://github.com/vercel/front/pull/29561
167 lines
15 KiB
Text
167 lines
15 KiB
Text
---
|
|
title: Next.js Project Structure
|
|
nav_title: Project Structure
|
|
description: A list of folders and files conventions in a Next.js project
|
|
---
|
|
|
|
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.
|
|
|
|
<Image
|
|
alt="Route segments to path segments"
|
|
srcLight="/docs/light/top-level-folders.png"
|
|
srcDark="/docs/dark/top-level-folders.png"
|
|
width="1600"
|
|
height="525"
|
|
/>
|
|
|
|
| | |
|
|
| ------------------------------------------------------------------------ | ---------------------------------- |
|
|
| [`app`](/docs/app/building-your-application/routing) | App Router |
|
|
| [`pages`](/docs/pages/building-your-application/routing) | Pages Router |
|
|
| [`public`](/docs/app/building-your-application/optimizing/static-assets) | Static assets to be served |
|
|
| [`src`](/docs/app/building-your-application/configuring/src-directory) | 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`](/docs/app/api-reference/next-config-js) | Configuration file for Next.js |
|
|
| [`package.json`](/docs/getting-started/installation#manual-installation) | Project dependencies and scripts |
|
|
| [`instrumentation.ts`](/docs/app/building-your-application/optimizing/instrumentation) | OpenTelemetry and Instrumentation file |
|
|
| [`middleware.ts`](/docs/app/building-your-application/routing/middleware) | Next.js request middleware |
|
|
| [`.env`](/docs/app/building-your-application/configuring/environment-variables) | Environment variables |
|
|
| [`.env.local`](/docs/app/building-your-application/configuring/environment-variables) | Local environment variables |
|
|
| [`.env.production`](/docs/app/building-your-application/configuring/environment-variables) | Production environment variables |
|
|
| [`.env.development`](/docs/app/building-your-application/configuring/environment-variables) | Development environment variables |
|
|
| [`.eslintrc.json`](/docs/app/building-your-application/configuring/eslint) | 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](/docs/app).
|
|
|
|
### Routing Files
|
|
|
|
| | | |
|
|
| ------------------------------------------------------------------------------- | ------------------- | ---------------------------- |
|
|
| [`layout`](/docs/app/api-reference/file-conventions/layout) | `.js` `.jsx` `.tsx` | Layout |
|
|
| [`page`](/docs/app/api-reference/file-conventions/page) | `.js` `.jsx` `.tsx` | Page |
|
|
| [`loading`](/docs/app/api-reference/file-conventions/loading) | `.js` `.jsx` `.tsx` | Loading UI |
|
|
| [`not-found`](/docs/app/api-reference/file-conventions/not-found) | `.js` `.jsx` `.tsx` | Not found UI |
|
|
| [`error`](/docs/app/api-reference/file-conventions/error) | `.js` `.jsx` `.tsx` | Error UI |
|
|
| [`global-error`](/docs/app/api-reference/file-conventions/error#global-errorjs) | `.js` `.jsx` `.tsx` | Global error UI |
|
|
| [`route`](/docs/app/api-reference/file-conventions/route) | `.js` `.ts` | API endpoint |
|
|
| [`template`](/docs/app/api-reference/file-conventions/template) | `.js` `.jsx` `.tsx` | Re-rendered layout |
|
|
| [`default`](/docs/app/api-reference/file-conventions/default) | `.js` `.jsx` `.tsx` | Parallel route fallback page |
|
|
|
|
### Nested Routes
|
|
|
|
| | |
|
|
| ---------------------------------------------------------------------------- | -------------------- |
|
|
| [`folder`](/docs/app/building-your-application/routing#route-segments) | Route segment |
|
|
| [`folder/folder`](/docs/app/building-your-application/routing#nested-routes) | Nested route segment |
|
|
|
|
### Dynamic Routes
|
|
|
|
| | |
|
|
| --------------------------------------------------------------------------------------------------------- | -------------------------------- |
|
|
| [`[folder]`](/docs/app/building-your-application/routing/dynamic-routes#convention) | Dynamic route segment |
|
|
| [`[...folder]`](/docs/app/building-your-application/routing/dynamic-routes#catch-all-segments) | Catch-all route segment |
|
|
| [`[[...folder]]`](/docs/app/building-your-application/routing/dynamic-routes#optional-catch-all-segments) | Optional catch-all route segment |
|
|
|
|
### Route Groups and Private Folders
|
|
|
|
| | |
|
|
| ----------------------------------------------------------------------------------- | ------------------------------------------------ |
|
|
| [`(folder)`](/docs/app/building-your-application/routing/route-groups#convention) | Group routes without affecting routing |
|
|
| [`_folder`](/docs/app/building-your-application/routing/colocation#private-folders) | Opt folder and all child segments out of routing |
|
|
|
|
### Parallel and Intercepted Routes
|
|
|
|
| | |
|
|
| ---------------------------------------------------------------------------------------------- | -------------------------- |
|
|
| [`@folder`](/docs/app/building-your-application/routing/parallel-routes#slots) | Named slot |
|
|
| [`(.)folder`](/docs/app/building-your-application/routing/intercepting-routes#convention) | Intercept same level |
|
|
| [`(..)folder`](/docs/app/building-your-application/routing/intercepting-routes#convention) | Intercept one level above |
|
|
| [`(..)(..)folder`](/docs/app/building-your-application/routing/intercepting-routes#convention) | Intercept two levels above |
|
|
| [`(...)folder`](/docs/app/building-your-application/routing/intercepting-routes#convention) | Intercept from root |
|
|
|
|
### Metadata File Conventions
|
|
|
|
#### App Icons
|
|
|
|
| | | |
|
|
| --------------------------------------------------------------------------------------------------------------- | ----------------------------------- | ------------------------ |
|
|
| [`favicon`](/docs/app/api-reference/file-conventions/metadata/app-icons#favicon) | `.ico` | Favicon file |
|
|
| [`icon`](/docs/app/api-reference/file-conventions/metadata/app-icons#icon) | `.ico` `.jpg` `.jpeg` `.png` `.svg` | App Icon file |
|
|
| [`icon`](/docs/app/api-reference/file-conventions/metadata/app-icons#generate-icons-using-code-js-ts-tsx) | `.js` `.ts` `.tsx` | Generated App Icon |
|
|
| [`apple-icon`](/docs/app/api-reference/file-conventions/metadata/app-icons#apple-icon) | `.jpg` `.jpeg`, `.png` | Apple App Icon file |
|
|
| [`apple-icon`](/docs/app/api-reference/file-conventions/metadata/app-icons#generate-icons-using-code-js-ts-tsx) | `.js` `.ts` `.tsx` | Generated Apple App Icon |
|
|
|
|
#### Open Graph and Twitter Images
|
|
|
|
| | | |
|
|
| --------------------------------------------------------------------------------------------------------------------------- | ---------------------------- | -------------------------- |
|
|
| [`opengraph-image`](/docs/app/api-reference/file-conventions/metadata/opengraph-image#opengraph-image) | `.jpg` `.jpeg` `.png` `.gif` | Open Graph image file |
|
|
| [`opengraph-image`](/docs/app/api-reference/file-conventions/metadata/opengraph-image#generate-images-using-code-js-ts-tsx) | `.js` `.ts` `.tsx` | Generated Open Graph image |
|
|
| [`twitter-image`](/docs/app/api-reference/file-conventions/metadata/opengraph-image#twitter-image) | `.jpg` `.jpeg` `.png` `.gif` | Twitter image file |
|
|
| [`twitter-image`](/docs/app/api-reference/file-conventions/metadata/opengraph-image#generate-images-using-code-js-ts-tsx) | `.js` `.ts` `.tsx` | Generated Twitter image |
|
|
|
|
#### SEO
|
|
|
|
| | | |
|
|
| ------------------------------------------------------------------------------------------------------------ | ----------- | --------------------- |
|
|
| [`sitemap`](/docs/app/api-reference/file-conventions/metadata/sitemap#sitemap-files-xml) | `.xml` | Sitemap file |
|
|
| [`sitemap`](/docs/app/api-reference/file-conventions/metadata/sitemap#generating-a-sitemap-using-code-js-ts) | `.js` `.ts` | Generated Sitemap |
|
|
| [`robots`](/docs/app/api-reference/file-conventions/metadata/robots#static-robotstxt) | `.txt` | Robots file |
|
|
| [`robots`](/docs/app/api-reference/file-conventions/metadata/robots#generate-a-robots-file) | `.js` `.ts` | Generated Robots file |
|
|
|
|
## `pages` Routing Conventions
|
|
|
|
The following file conventions are used to define routes in the [`pages` router](/docs/pages).
|
|
|
|
### Special Files
|
|
|
|
| | | |
|
|
| ----------------------------------------------------------------------------------------------------------- | ------------------- | ----------------- |
|
|
| [`_app`](/docs/pages/building-your-application/routing/custom-app) | `.js` `.jsx` `.tsx` | Custom App |
|
|
| [`_document`](/docs/pages/building-your-application/routing/custom-document) | `.js` `.jsx` `.tsx` | Custom Document |
|
|
| [`_error`](/docs/pages/building-your-application/routing/custom-error#more-advanced-error-page-customizing) | `.js` `.jsx` `.tsx` | Custom Error Page |
|
|
| [`404`](/docs/pages/building-your-application/routing/custom-error#404-page) | `.js` `.jsx` `.tsx` | 404 Error Page |
|
|
| [`500`](/docs/pages/building-your-application/routing/custom-error#500-page) | `.js` `.jsx` `.tsx` | 500 Error Page |
|
|
|
|
### Routes
|
|
|
|
| | | |
|
|
| ---------------------------------------------------------------------------------------------- | ------------------- | ----------- |
|
|
| **Folder convention** | | |
|
|
| [`index`](/docs/pages/building-your-application/routing/pages-and-layouts#index-routes) | `.js` `.jsx` `.tsx` | Home page |
|
|
| [`folder/index`](/docs/pages/building-your-application/routing/pages-and-layouts#index-routes) | `.js` `.jsx` `.tsx` | Nested page |
|
|
| **File convention** | | |
|
|
| [`index`](/docs/pages/building-your-application/routing/pages-and-layouts#index-routes) | `.js` `.jsx` `.tsx` | Home page |
|
|
| [`file`](/docs/pages/building-your-application/routing/pages-and-layouts) | `.js` `.jsx` `.tsx` | Nested page |
|
|
|
|
### Dynamic Routes
|
|
|
|
| | | |
|
|
| ----------------------------------------------------------------------------------------------------------------- | ------------------- | -------------------------------- |
|
|
| **Folder convention** | | |
|
|
| [`[folder]/index`](/docs/pages/building-your-application/routing/dynamic-routes) | `.js` `.jsx` `.tsx` | Dynamic route segment |
|
|
| [`[...folder]/index`](/docs/pages/building-your-application/routing/dynamic-routes#catch-all-segments) | `.js` `.jsx` `.tsx` | Catch-all route segment |
|
|
| [`[[...folder]]/index`](/docs/pages/building-your-application/routing/dynamic-routes#optional-catch-all-segments) | `.js` `.jsx` `.tsx` | Optional catch-all route segment |
|
|
| **File convention** | | |
|
|
| [`[file]`](/docs/pages/building-your-application/routing/dynamic-routes) | `.js` `.jsx` `.tsx` | Dynamic route segment |
|
|
| [`[...file]`](/docs/pages/building-your-application/routing/dynamic-routes#catch-all-segments) | `.js` `.jsx` `.tsx` | Catch-all route segment |
|
|
| [`[[...file]]`](/docs/pages/building-your-application/routing/dynamic-routes#optional-catch-all-segments) | `.js` `.jsx` `.tsx` | Optional catch-all route segment |
|