Getting Started Docs: Improve "Project Structure" page (#72399)

Closes: - https://linear.app/vercel/issue/DOC-3695/page-project-structure This PR: - Splits the page between the app/pages and the router docs. - Merge the colocation page from BYA.
vercel · Nov 7, 2024 · 224447c · 224447c
1 parent 5f0adad
commit 224447c
Show file tree

Hide file tree

Showing 7 changed files with 179 additions and 210 deletions.
diff --git a/docs/01-app/01-getting-started/02-project-structure.mdx b/docs/01-app/01-getting-started/02-project-structure.mdx
@@ -1,14 +1,14 @@
 ---
-title: Next.js Project Structure
+title: Project Structure and Organization
 nav_title: Project Structure
-description: A list of folders and files conventions in a Next.js project
+description: Learn about the folder and file conventions in a Next.js project, and how to organize your 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.
+This page provides an overview of the folder and file conventions in Next.js, as well as tips for organizing your project.
 
-Click the file and folder names to learn more about each convention.
+## Folder and file conventions
 
-## Top-level folders
+### Top-level folders
 
 Top-level folders are used to organize your application's code and static assets.
 
@@ -27,7 +27,7 @@ Top-level folders are used to organize your application's code and static assets
 | [`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
 
 Top-level files are used to configure your application, manage dependencies, run middleware, integrate monitoring tools, and define environment variables.
 
@@ -48,9 +48,7 @@ Top-level files are used to configure your application, manage dependencies, run
 | `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).
+<AppOnly>
 
 ### Routing Files
 
@@ -66,27 +64,27 @@ The following file conventions are used to define routes and handle metadata in
 | [`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
+### 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
+### 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
+### 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 |
+|                                                                                   |                                                  |
+| --------------------------------------------------------------------------------- | ------------------------------------------------ |
+| [`(folder)`](/docs/app/building-your-application/routing/route-groups#convention) | Group routes without affecting routing           |
+| [`_folder`](#private-folders)                                                     | Opt folder and all child segments out of routing |
 
 ### Parallel and Intercepted Routes
 
@@ -98,9 +96,9 @@ The following file conventions are used to define routes and handle metadata in
 | [`(..)(..)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
+### Metadata file conventions
 
-#### App Icons
+#### App icons
 
 |                                                                                                                 |                                     |                          |
 | --------------------------------------------------------------------------------------------------------------- | ----------------------------------- | ------------------------ |
@@ -110,7 +108,7 @@ The following file conventions are used to define routes and handle metadata in
 | [`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
+#### Open Graph and Twitter images
 
 |                                                                                                                             |                              |                            |
 | --------------------------------------------------------------------------------------------------------------------------- | ---------------------------- | -------------------------- |
@@ -128,11 +126,11 @@ The following file conventions are used to define routes and handle metadata in
 | [`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
+</AppOnly>
 
-The following file conventions are used to define routes in the [`pages` router](/docs/pages).
+<PagesOnly>
 
-### Special Files
+### Files conventions
 
 |                                                                                                             |                     |                   |
 | ----------------------------------------------------------------------------------------------------------- | ------------------- | ----------------- |
@@ -153,7 +151,7 @@ The following file conventions are used to define routes in the [`pages` router]
 | [`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
+### Dynamic routes
 
 |                                                                                                                   |                     |                                  |
 | ----------------------------------------------------------------------------------------------------------------- | ------------------- | -------------------------------- |
@@ -165,3 +163,151 @@ The following file conventions are used to define routes in the [`pages` router]
 | [`[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 |
+
+</PagesOnly>
+
+<AppOnly>
+
+## Organizing your project
+
+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.
+
+### Colocation
+
+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.
+
+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.
+
+<Image
+  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."
+  srcLight="/docs/light/project-organization-not-routable.png"
+  srcDark="/docs/dark/project-organization-not-routable.png"
+  width="1600"
+  height="444"
+/>
+
+And, even when a route is made publicly accessible, only the **content returned** by `page.js` or `route.js` is sent to the client.
+
+<Image
+  alt="A diagram showing how page.js and route.js files make routes publicly accessible."
+  srcLight="/docs/light/project-organization-routable.png"
+  srcDark="/docs/dark/project-organization-routable.png"
+  width="1600"
+  height="687"
+/>
+
+This means that **project files** can be **safely colocated** inside route segments in the `app` directory without accidentally being routable.
+
+<Image
+  alt="A diagram showing colocated project files are not routable even when a segment contains a page.js or route.js file."
+  srcLight="/docs/light/project-organization-colocation.png"
+  srcDark="/docs/dark/project-organization-colocation.png"
+  width="1600"
+  height="1011"
+/>
+
+> **Good to know**:
+>
+> - 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).
+
+### Private folders
+
+Private folders can be created by prefixing a folder with an underscore: `_folderName`
+
+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.
+
+<Image
+  alt="An example folder structure using private folders"
+  srcLight="/docs/light/project-organization-private-folders.png"
+  srcDark="/docs/dark/project-organization-private-folders.png"
+  width="1600"
+  height="849"
+/>
+
+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:
+
+- Separating UI logic from routing logic.
+- Consistently organizing internal files across a project and the Next.js ecosystem.
+- Sorting and grouping files in code editors.
+- Avoiding potential naming conflicts with future Next.js file conventions.
+
+> **Good to know**:
+>
+> - While not a framework convention, you might also consider marking files outside private folders as "private" using the same underscore pattern.
+> - 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`.
+> - 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.
+
+### Route groups
+
+Route groups can be created by wrapping a folder in parenthesis: `(folderName)`
+
+This indicates the folder is for organizational purposes and should **not be included** in the route's URL path.
+
+<Image
+  alt="An example folder structure using route groups"
+  srcLight="/docs/light/project-organization-route-groups.png"
+  srcDark="/docs/dark/project-organization-route-groups.png"
+  width="1600"
+  height="849"
+/>
+
+Route groups are useful for:
+
+- [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.
+- Enabling nested layouts in the same route segment level:
+  - [Creating multiple nested layouts in the same segment, including multiple root layouts](/docs/app/building-your-application/routing/route-groups#creating-multiple-root-layouts)
+  - [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)
+
+### `src` directory
+
+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.
+
+<Image
+  alt="An example folder structure with the `src` directory"
+  srcLight="/docs/light/project-organization-src-directory.png"
+  srcDark="/docs/dark/project-organization-src-directory.png"
+  width="1600"
+  height="687"
+/>
+
+### Common strategies
+
+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.
+
+> **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.
+
+#### Store project files outside of `app`
+
+This strategy stores all application code in shared folders in the **root of your project** and keeps the `app` directory purely for routing purposes.
+
+<Image
+  alt="An example folder structure with project files outside of app"
+  srcLight="/docs/light/project-organization-project-root.png"
+  srcDark="/docs/dark/project-organization-project-root.png"
+  width="1600"
+  height="849"
+/>
+
+#### Store project files in top-level folders inside of `app`
+
+This strategy stores all application code in shared folders in the **root of the `app` directory**.
+
+<Image
+  alt="An example folder structure with project files inside app"
+  srcLight="/docs/light/project-organization-app-root.png"
+  srcDark="/docs/dark/project-organization-app-root.png"
+  width="1600"
+  height="849"
+/>
+
+#### Split project files by feature or route
+
+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.
+
+<Image
+  alt="An example folder structure with project files split by feature or route"
+  srcLight="/docs/light/project-organization-app-root-split.png"
+  srcDark="/docs/dark/project-organization-app-root-split.png"
+  width="1600"
+  height="1011"
+/>
diff --git a/docs/01-app/01-getting-started/index.mdx b/docs/01-app/01-getting-started/index.mdx
@@ -1,4 +1,5 @@
 ---
-title: Getting Started
-description: Learn how to create full-stack web applications with Next.js.
+title: Getting Started - App Router
+nav_title: Getting Started
+description: Learn how to create full-stack web applications with the Next.js App Router.
 ---