Unverified Commit 04cc37f7 authored by Scotty Waggoner's avatar Scotty Waggoner Committed by GitHub

Add docs for using pageExtensions to colocate other files with page components (#22740)

Feel free to edit this/suggest changes as you see fit to match the style of your docs or how you want this feature represented.

There seemed to be many issues regarding colocating non-page files with page components in  the `pages` directory where `pageExtensions` was finally suggested as a solution. I think it would be great to document it better since it seems to be a often requested workflow to colocate test, generated files, styles, and other files needed by page components in the `pages` directory. The note that exists in the docs currently alludes to the ability to do this but it doesn't contain much context that would help make it more discoverable.

Relevant issues:
https://github.com/vercel/next.js/discussions/11113#discussioncomment-427139
https://github.com/vercel/next.js/issues/8454#issuecomment-560432659
https://github.com/vercel/next.js/issues/8617#issuecomment-790030032
https://github.com/vercel/next.js/issues/3728#issuecomment-523789071
parent f1dbc926
...@@ -14,8 +14,37 @@ module.exports = { ...@@ -14,8 +14,37 @@ module.exports = {
} }
``` ```
> **Note**: The default value of `pageExtensions` is [`['tsx', 'ts', 'jsx', 'js']`](https://github.com/vercel/next.js/blob/f1dbc9260d48c7995f6c52f8fbcc65f08e627992/packages/next/server/config-shared.ts#L161).
> **Note**: configuring `pageExtensions` also affects `_document.js`, `_app.js` as well as files under `pages/api/`. For example, setting `pageExtensions: ['page.tsx', 'page.ts']` means the following files: `_document.tsx`, `_app.tsx`, `pages/users.tsx` and `pages/api/users.ts` will have to be renamed to `_document.page.tsx`, `_app.page.tsx`, `pages/users.page.tsx` and `pages/api/users.page.ts` respectively. > **Note**: configuring `pageExtensions` also affects `_document.js`, `_app.js` as well as files under `pages/api/`. For example, setting `pageExtensions: ['page.tsx', 'page.ts']` means the following files: `_document.tsx`, `_app.tsx`, `pages/users.tsx` and `pages/api/users.ts` will have to be renamed to `_document.page.tsx`, `_app.page.tsx`, `pages/users.page.tsx` and `pages/api/users.page.ts` respectively.
## Including non-page files in the `pages` directory
To colocate test files, generated files, or other files used by components in the `pages` directory, you can prefix the extensions with something like `page`.
Open `next.config.js` and add the `pageExtensions` config:
```js
module.exports = {
pageExtensions: ['page.tsx', 'page.ts', 'page.jsx', 'page.js'],
}
```
Then rename your pages to have a file extension that includes `.page` (ex. rename `MyPage.tsx` to `MyPage.page.tsx`).
> **Note**: Make sure you also rename `_document.js`, `_app.js` as well as files under `pages/api/`.
Without this config, Next.js assumes every tsx/ts/jsx/js file in the `pages` directory is a page or API route, and may expose unintended routes vulnerable to denial of service attacks, or throw an error like the following when building the production bundle:
```
Build error occurred
Error: Build optimization failed: found pages without a React Component as default export in
pages/MyPage.generated
pages/MyPage.test
See https://nextjs.org/docs/messages/page-without-valid-component for more info.
```
## Related ## Related
<div class="card"> <div class="card">
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment