Unverified Commit 4f793fd7 authored by Lee Robinson's avatar Lee Robinson Committed by GitHub

[docs] Improve documentation around `pageExtensions` (#40039)

Reverts vercel/next.js#40016.

`pageExtensions` is not frequently used – as is mostly a workaround
until the Layouts RFC lands. Thus, it doesn't make sense to place a note
on the Middleware page and expect readers to need to connect the dots
and understand `pageExtensions`.

Further, the example docs linked could be more specific about Middleware
to prevent this confusion. I will also make that change here.
Co-authored-by: 's avatarBalázs Orbán <info@balazsorban.com>
parent 93ff04b4
...@@ -50,8 +50,6 @@ export const config = { ...@@ -50,8 +50,6 @@ export const config = {
} }
``` ```
> **Note** the `pageExtensions` config affects middleware as well, [see related documentation here](/docs/api-reference/next.config.js/custom-page-extensions.md).
## Matching Paths ## Matching Paths
Middleware will be invoked for **every route in your project**. The following is the execution order: Middleware will be invoked for **every route in your project**. The following is the execution order:
......
...@@ -4,9 +4,7 @@ description: Extend the default page extensions used by Next.js when resolving p ...@@ -4,9 +4,7 @@ description: Extend the default page extensions used by Next.js when resolving p
# Custom Page Extensions # Custom Page Extensions
Aimed at modules like [@next/mdx](https://github.com/vercel/next.js/tree/canary/packages/next-mdx), which adds support for pages ending with `.mdx`. You can configure the extensions looked for in the `pages` directory when resolving pages. You can extend the default Page extensions (`.tsx`, `.ts`, `.jsx`, `.js`) used by Next.js. Inside `next.config.js`, add the `pageExtensions` config:
Open `next.config.js` and add the `pageExtensions` config:
```js ```js
module.exports = { module.exports = {
...@@ -14,15 +12,18 @@ module.exports = { ...@@ -14,15 +12,18 @@ 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). Changing these values affects _all_ Next.js pages, including the following:
> **Note**: configuring `pageExtensions` also affects `_document.js`, `_app.js`, `middleware.js` as well as files under `pages/api/`. For example, setting `pageExtensions: ['page.tsx', 'page.ts']` means the following files: `_document.tsx`, `_app.tsx`, `middleware.ts`, `pages/users.tsx` and `pages/api/users.ts` will have to be renamed to `_document.page.tsx`, `_app.page.tsx`, `middleware.page.ts`, `pages/users.page.tsx` and `pages/api/users.page.ts` respectively. - `middleware.js`
- `pages/_document.js`
- `pages/_app.js`
- `pages/api/`
## Including non-page files in the `pages` directory For example, if you reconfigure `.ts` page extensions to `.page.ts`, you would need to rename pages like `_app.page.ts`.
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`. ## Including non-page files in the `pages` directory
Open `next.config.js` and add the `pageExtensions` config: You can colocate test files or other files used by components in the `pages` directory. Inside `next.config.js`, add the `pageExtensions` config:
```js ```js
module.exports = { module.exports = {
...@@ -30,20 +31,7 @@ module.exports = { ...@@ -30,20 +31,7 @@ module.exports = {
} }
``` ```
Then rename your pages to have a file extension that includes `.page` (ex. rename `MyPage.tsx` to `MyPage.page.tsx`). Then, rename your pages to have a file extension that includes `.page` (e.g. rename `MyPage.tsx` to `MyPage.page.tsx`). Ensure you rename _all_ Next.js pages, including the files mentioned above.
> **Note**: Make sure you also rename `_document.js`, `_app.js`, `middleware.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
......
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