From 224447cd65d23f2dec2119b0c9ef10b79532dc6e Mon Sep 17 00:00:00 2001 From: Delba de Oliveira <32464864+delbaoliveira@users.noreply.github.com> Date: Thu, 7 Nov 2024 01:34:46 -0800 Subject: [PATCH] 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. --- .../02-project-structure.mdx | 192 +++++++++++++++--- docs/01-app/01-getting-started/index.mdx | 5 +- .../01-routing/09-colocation.mdx | 179 ---------------- .../01-routing/index.mdx | 2 +- .../07-configuring/06-src-directory.mdx | 2 +- .../02-project-structure.mdx | 4 +- docs/02-pages/01-getting-started/index.mdx | 5 +- 7 files changed, 179 insertions(+), 210 deletions(-) delete mode 100644 docs/01-app/02-building-your-application/01-routing/09-colocation.mdx diff --git a/docs/01-app/01-getting-started/02-project-structure.mdx b/docs/01-app/01-getting-started/02-project-structure.mdx index 979f0de2546d0..4b87dde383685 100644 --- 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). + ### Routing Files @@ -66,14 +64,14 @@ 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 | | | | --------------------------------------------------------------------------------------------------------- | -------------------------------- | @@ -81,12 +79,12 @@ The following file conventions are used to define routes and handle metadata in | [`[...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 + -The following file conventions are used to define routes in the [`pages` router](/docs/pages). + -### 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 | + + + + + +## 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. + +A diagram showing how a route is not publicly accessible until a page.js or route.js file is added to a route segment. + +And, even when a route is made publicly accessible, only the **content returned** by `page.js` or `route.js` is sent to the client. + +A diagram showing how page.js and route.js files make routes publicly accessible. + +This means that **project files** can be **safely colocated** inside route segments in the `app` directory without accidentally being routable. + +A diagram showing colocated project files are not routable even when a segment contains a page.js or route.js file. + +> **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. + +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: + +- 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. + +An example folder structure using route groups + +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. + +An example folder structure with the `src` directory + +### 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. + +An example folder structure with project files outside of app + +#### 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**. + +An example folder structure with project files inside app + +#### 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. + +An example folder structure with project files split by feature or route diff --git a/docs/01-app/01-getting-started/index.mdx b/docs/01-app/01-getting-started/index.mdx index df84fb94cf135..606e180da5a77 100644 --- 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. --- diff --git a/docs/01-app/02-building-your-application/01-routing/09-colocation.mdx b/docs/01-app/02-building-your-application/01-routing/09-colocation.mdx deleted file mode 100644 index a2e09b83c0763..0000000000000 --- a/docs/01-app/02-building-your-application/01-routing/09-colocation.mdx +++ /dev/null @@ -1,179 +0,0 @@ ---- -title: Project Organization and File Colocation -nav_title: Project Organization -description: Learn how to organize your Next.js project and colocate files. -related: - links: - - app/building-your-application/routing/defining-routes - - app/building-your-application/routing/route-groups - - app/building-your-application/configuring/src-directory ---- - -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. - -This page shares default behavior and features you can use to organize your project. - -- [Safe colocation by default](#safe-colocation-by-default) -- [Project organization features](#project-organization-features) -- [Project organization strategies](#project-organization-strategies) - -## Safe colocation by default - -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. - -A diagram showing how a route is not publicly accessible until a page.js or route.js file is added to a route segment. - -And, even when a route is made publicly accessible, only the **content returned** by `page.js` or `route.js` is sent to the client. - -A diagram showing how page.js and route.js files make routes publicly accessible. - -This means that **project files** can be **safely colocated** inside route segments in the `app` directory without accidentally being routable. - -A diagram showing colocated project files are not routable even when a segment contains a page.js or route.js file. - -> **Good to know**: -> -> - This is different from the `pages` directory, where any file in `pages` is considered a route. -> - 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). - -## Project organization features - -Next.js provides several features to help you organize your project. - -### 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. - -An example folder structure using private folders - -Since files in the `app` directory can be [safely colocated by default](#safe-colocation-by-default), 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. - -An example folder structure using route groups - -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. - -An example folder structure with the `src` directory - -### Module Path Aliases - -Next.js supports [Module Path Aliases](/docs/app/getting-started/installation#set-up-absolute-imports-and-module-path-aliases) which make it easier to read and maintain imports across deeply nested project files. - -```jsx filename="app/dashboard/settings/analytics/page.js" -// before -import { Button } from '../../../components/button' - -// after -import { Button } from '@/components/button' -``` - -## Project organization strategies - -There is no "right" or "wrong" way when it comes to organizing your own files and folders in a Next.js project. - -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. - -An example folder structure with project files outside of app - -### 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**. - -An example folder structure with project files inside app - -### 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. - -An example folder structure with project files split by feature or route diff --git a/docs/01-app/02-building-your-application/01-routing/index.mdx b/docs/01-app/02-building-your-application/01-routing/index.mdx index 9fd5f906d65aa..366549e83ad0d 100644 --- a/docs/01-app/02-building-your-application/01-routing/index.mdx +++ b/docs/01-app/02-building-your-application/01-routing/index.mdx @@ -144,7 +144,7 @@ This is because while folders define routes, only the contents returned by `page height="1011" /> -Learn more about [Project Organization and Colocation](/docs/app/building-your-application/routing/colocation). +Learn more about [Project Organization and Colocation](/docs/app/getting-started/project-structure#colocation). ## Advanced Routing Patterns diff --git a/docs/01-app/02-building-your-application/07-configuring/06-src-directory.mdx b/docs/01-app/02-building-your-application/07-configuring/06-src-directory.mdx index d815769033b27..1a7353c7e5c35 100644 --- a/docs/01-app/02-building-your-application/07-configuring/06-src-directory.mdx +++ b/docs/01-app/02-building-your-application/07-configuring/06-src-directory.mdx @@ -3,7 +3,7 @@ title: src Directory description: Save pages under the `src` directory as an alternative to the root `pages` directory. related: links: - - app/building-your-application/routing/colocation + - app/getting-started/project-structure --- {/* The content of this doc is shared between the app and pages router. You can use the `Content` component to add content that is specific to the Pages Router. Any shared content should not be wrapped in a component. */} diff --git a/docs/02-pages/01-getting-started/02-project-structure.mdx b/docs/02-pages/01-getting-started/02-project-structure.mdx index cdfb9564fa358..c4be62c32b06f 100644 --- a/docs/02-pages/01-getting-started/02-project-structure.mdx +++ b/docs/02-pages/01-getting-started/02-project-structure.mdx @@ -1,7 +1,7 @@ --- -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. source: app/getting-started/project-structure --- diff --git a/docs/02-pages/01-getting-started/index.mdx b/docs/02-pages/01-getting-started/index.mdx index df84fb94cf135..17447669def9e 100644 --- a/docs/02-pages/01-getting-started/index.mdx +++ b/docs/02-pages/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 - Pages Router +nav_title: Getting Started +description: Learn how to create full-stack web applications with Next.js with the Pages Router. ---