You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
description: A list of folders and files conventions in a Next.js project
4
+
description: Learn about the folder and file conventions in a Next.js project, and how to organize your project.
5
5
---
6
6
7
-
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.
7
+
This page provides an overview of the folder and file conventions in Next.js, as well as tips for organizing your project.
8
8
9
-
Click the file and folder names to learn more about each convention.
9
+
## Folder and file conventions
10
10
11
-
## Top-level folders
11
+
###Top-level folders
12
12
13
13
Top-level folders are used to organize your application's code and static assets.
14
14
@@ -27,7 +27,7 @@ Top-level folders are used to organize your application's code and static assets
27
27
|[`public`](/docs/app/building-your-application/optimizing/static-assets)| Static assets to be served |
Top-level files are used to configure your application, manage dependencies, run middleware, integrate monitoring tools, and define environment variables.
33
33
@@ -48,9 +48,7 @@ Top-level files are used to configure your application, manage dependencies, run
48
48
|`tsconfig.json`| Configuration file for TypeScript |
49
49
|`jsconfig.json`| Configuration file for JavaScript |
50
50
51
-
## `app` Routing Conventions
52
-
53
-
The following file conventions are used to define routes and handle metadata in the [`app` router](/docs/app).
51
+
<AppOnly>
54
52
55
53
### Routing Files
56
54
@@ -66,27 +64,27 @@ The following file conventions are used to define routes and handle metadata in
Apart from [folder and file conventions](/docs/app/getting-started/project-structure), 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.
174
+
175
+
### Colocation
176
+
177
+
In the `app` directory, [nested folder hierarchy](/docs/app/building-your-application/routing#route-segments) defines route structure. Each folder represents a route segment that is mapped to a corresponding segment in a URL path.
178
+
179
+
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.
180
+
181
+
<Image
182
+
alt="A diagram showing how a route is not publicly accessible until a page.js or route.js file is added to a route segment."
> - While you **can** colocate your project files in `app` you don't **have** to. If you prefer, you can [keep them outside the `app` directory](#store-project-files-outside-of-app).
212
+
213
+
### Private folders
214
+
215
+
Private folders can be created by prefixing a folder with an underscore: `_folderName`
216
+
217
+
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.
218
+
219
+
<Image
220
+
alt="An example folder structure using private folders"
Since files in the `app` directory can be [safely colocated by default](#colocation), private folders are not required for colocation. However, they can be useful for:
228
+
229
+
- Separating UI logic from routing logic.
230
+
- Consistently organizing internal files across a project and the Next.js ecosystem.
231
+
- Sorting and grouping files in code editors.
232
+
- Avoiding potential naming conflicts with future Next.js file conventions.
233
+
234
+
> **Good to know**:
235
+
>
236
+
> - While not a framework convention, you might also consider marking files outside private folders as "private" using the same underscore pattern.
237
+
> - 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`.
238
+
> - If you don't use private folders, it would be helpful to know Next.js [special file conventions](/docs/app/getting-started/project-structure#routing-files) to prevent unexpected naming conflicts.
239
+
240
+
### Route groups
241
+
242
+
Route groups can be created by wrapping a folder in parenthesis: `(folderName)`
243
+
244
+
This indicates the folder is for organizational purposes and should **not be included** in the route's URL path.
245
+
246
+
<Image
247
+
alt="An example folder structure using route groups"
-[Organizing routes into groups](/docs/app/building-your-application/routing/route-groups#organize-routes-without-affecting-the-url-path) e.g. by site section, intent, or team.
257
+
- Enabling nested layouts in the same route segment level:
258
+
-[Creating multiple nested layouts in the same segment, including multiple root layouts](/docs/app/building-your-application/routing/route-groups#creating-multiple-root-layouts)
259
+
-[Adding a layout to a subset of routes in a common segment](/docs/app/building-your-application/routing/route-groups#opting-specific-segments-into-a-layout)
260
+
261
+
### `src` directory
262
+
263
+
Next.js supports storing application code (including `app`) inside an optional [`src` directory](/docs/app/building-your-application/configuring/src-directory). This separates application code from project configuration files which mostly live in the root of a project.
264
+
265
+
<Image
266
+
alt="An example folder structure with the `src` directory"
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.
276
+
277
+
> **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.
278
+
279
+
#### Store project files outside of `app`
280
+
281
+
This strategy stores all application code in shared folders in the **root of your project** and keeps the `app` directory purely for routing purposes.
282
+
283
+
<Image
284
+
alt="An example folder structure with project files outside of app"
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.
306
+
307
+
<Image
308
+
alt="An example folder structure with project files split by feature or route"
0 commit comments