Add docs for using pageExtensions to colocate other files with page c…

…omponents (#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:
#11113 (reply in thread)
#8454 (comment)
#8617 (comment)
#3728 (comment)

docs/api-reference/next.config.js/custom-page-extensions.md

@@ -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.
 
+## 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
 
 <div class="card">