docs: Migrate error messages to MDX and App Router. (#52038)

This PR is part of a larger effort to migrate error messages to MDX and
use App Router: vercel/front#23459

.github/workflows/validate-docs-links.yml

@@ -3,6 +3,7 @@ on:
   pull_request:
     paths:
       - 'docs/**.mdx'
+      - 'errors/*.mdx'
 
 jobs:
   link-check:

docs/02-app/02-api-reference/02-file-conventions/01-metadata/opengraph-image.mdx

@@ -339,7 +339,7 @@ export default function Image() {}
 This example uses the `params` object and external data to generate the image.
 
 > **Good to know**:
-> By default, this generated image will be [statically optimized](/docs/app/building-your-application/rendering/static-and-dynamic-rendering#static-rendering-default). You can configure the individual `fetch` [`options`](/docs/app/api-reference/functions/fetch) or route segments [options](docs/app/api-reference/file-conventions/route-segment-config#revalidate) to change this behavior.
+> By default, this generated image will be [statically optimized](/docs/app/building-your-application/rendering/static-and-dynamic-rendering#static-rendering-default). You can configure the individual `fetch` [`options`](/docs/app/api-reference/functions/fetch) or route segments [options](/docs/app/api-reference/file-conventions/route-segment-config#revalidate) to change this behavior.
 
 ```tsx filename="app/posts/[slug]/opengraph-image.tsx" switcher
 import { ImageResponse } from 'next/server'

docs/03-pages/02-api-reference/02-functions/get-server-side-props.mdx

@@ -54,7 +54,7 @@ The `context` parameter is an object containing the following keys:
 | `query`         | An object representing the query string, including dynamic route parameters.                                                                                                                                          |
 | `preview`       | (Deprecated for `draftMode`) `preview` is `true` if the page is in the [Preview Mode](/docs/pages/building-your-application/configuring/preview-mode) and `false` otherwise.                                          |
 | `previewData`   | (Deprecated for `draftMode`) The [preview](/docs/pages/building-your-application/configuring/preview-mode) data set by `setPreviewData`.                                                                              |
-| `draftMode`     | `draftMode` is `true` if the page is in the [Draft Mode](docs/pages/building-your-application/configuring/draft-mode) and `false` otherwise.                                                                          |
+| `draftMode`     | `draftMode` is `true` if the page is in the [Draft Mode](/docs/pages/building-your-application/configuring/draft-mode) and `false` otherwise.                                                                         |
 | `resolvedUrl`   | A normalized version of the request `URL` that strips the `_next/data` prefix for client transitions and includes original query values.                                                                              |
 | `locale`        | Contains the active locale (if enabled).                                                                                                                                                                              |
 | `locales`       | Contains all supported locales (if enabled).                                                                                                                                                                          |

docs/03-pages/02-api-reference/02-functions/get-static-props.mdx

@@ -51,7 +51,7 @@ The `context` parameter is an object containing the following keys:
 | `params`        | Contains the route parameters for pages using [dynamic routes](/docs/pages/building-your-application/routing/dynamic-routes). For example, if the page name is `[id].js`, then `params` will look like `{ id: ... }`. You should use this together with `getStaticPaths`, which we'll explain later. |
 | `preview`       | (Deprecated for `draftMode`) `preview` is `true` if the page is in the [Preview Mode](/docs/pages/building-your-application/configuring/preview-mode) and `false` otherwise.                                                                                                                         |
 | `previewData`   | (Deprecated for `draftMode`) The [preview](/docs/pages/building-your-application/configuring/preview-mode) data set by `setPreviewData`.                                                                                                                                                             |
-| `draftMode`     | `draftMode` is `true` if the page is in the [Draft Mode](docs/pages/building-your-application/configuring/draft-mode) and `false` otherwise.                                                                                                                                                         |
+| `draftMode`     | `draftMode` is `true` if the page is in the [Draft Mode](/docs/pages/building-your-application/configuring/draft-mode) and `false` otherwise.                                                                                                                                                        |
 | `locale`        | Contains the active locale (if enabled).                                                                                                                                                                                                                                                             |
 | `locales`       | Contains all supported locales (if enabled).                                                                                                                                                                                                                                                         |
 | `defaultLocale` | Contains the configured default locale (if enabled).                                                                                                                                                                                                                                                 |

errors/404-get-initial-props.md → errors/404-get-initial-props.mdx

@@ -1,15 +1,17 @@
-# 404.js Cannot Have getInitialProps
+---
+title: 404.js Cannot Have getInitialProps
+---
 
-#### Why This Error Occurred
+## Why This Error Occurred
 
 In your `404.js` page you added `getInitialProps` or `getServerSideProps` which is not allowed as this prevents the page from being static and `404.js` is meant to provide more flexibility for a static 404 page. Having a static 404 page is the most ideal as this page can be served very often and if not static puts extra strain on your server and more invocations for serverless functions which increase the cost of hosting your site unnecessarily.
 
-#### Possible Ways to Fix It
+## Possible Ways to Fix It
 
 Remove `getInitialProps` from `404.js` and make sure no HOC's used in `404.js` attach `getInitialProps`.
 
 If you want to fetch data for your `404.js` page move it to a client side fetch inside of `componentDidMount` or `useEffect(() => {}, [])`.
 
-### Useful Links
+## Useful Links
 
-- [Automatic Static Optimization](https://nextjs.org/docs/advanced-features/automatic-static-optimization)
+- [Automatic Static Optimization](/docs/pages/building-your-application/rendering/automatic-static-optimization)

errors/amp-bind-jsx-alt.md → errors/amp-bind-jsx-alt.mdx

@@ -1,14 +1,16 @@
-# AMP Bind JSX Error
+---
+title: AMP Bind JSX Error
+---
 
-#### Why This Error Occurred
+## Why This Error Occurred
 
 Somewhere you used `[prop]='something'` syntax which is not allowed in JSX.
 
-#### Possible Ways to Fix It
+## Possible Ways to Fix It
 
 Instead you can use `data-amp-bind-prop='something'` which is a valid AMP alternative
 
-### Useful Links
+## Useful Links
 
 - [AMP HTML Specification](https://www.ampproject.org/docs/fundamentals/spec)
 - [Possible future syntax](https://github.com/ampproject/amphtml/issues/21600)

errors/amp-export-validation.md → errors/amp-export-validation.mdx

@@ -1,15 +1,17 @@
-# AMP Export Validation
+---
+title: AMP Export Validation
+---
 
-#### Why This Error Occurred
+## Why This Error Occurred
 
 During export we validate AMP pages using [amphtml-validator](https://www.npmjs.com/package/amphtml-validator). Errors received from the validator will fail the export.
 
 Validation errors will cause pages to not be [indexed by AMP Caches](https://www.ampproject.org/docs/fundamentals/how_cached).
 
-#### Possible Ways to Fix It
+## Possible Ways to Fix It
 
 Look at the error messages and follow their appropriate links to learn more about the error and how to correct the problem.
 
-### Useful Links
+## Useful Links
 
 - [AMP HTML Specification](https://www.ampproject.org/docs/fundamentals/spec)

errors/api-routes-response-size-limit.md → errors/api-routes-response-size-limit.mdx

@@ -1,14 +1,16 @@
-# API Routes Response Size Limited to 4MB
+---
+title: API Routes Response Size Limited to 4MB
+---
 
-#### Why This Error Occurred
+## Why This Error Occurred
 
 API Routes are meant to respond quickly and are not intended to support responding with large amounts of data. The maximum size of responses is 4MB.
 
-#### Possible Ways to Fix It
+## Possible Ways to Fix It
 
 If you are not using Next.js in a serverless environment, and understand the performance implications of not using a CDN or dedicated media host, you can set this limit to `false` inside your API Route.
 
-```js
+```js filename="pages/api/example.js"
 export const config = {
   api: {
     responseLimit: false,
@@ -19,7 +21,7 @@ export const config = {
 `responseLimit` can also take the number of bytes or any string format supported by `bytes`, for example `1000`, `'500kb'` or `'3mb'`.
 This value will be the maximum response size before a warning is displayed. The default value is 4MB.
 
-```js
+```js filename="pages/api/example.js"
 export const config = {
   api: {
     responseLimit: '8mb',

errors/api-routes-static-export.md → errors/api-routes-static-export.mdx

@@ -1,15 +1,17 @@
-# API routes in Static export
+---
+title: API routes in Static export
+---
 
 #### Why This Warning Occurred
 
 An `exportPathMap` path was matched to an API route. Statically exporting a Next.js application via `next export` disables API routes.
 
 This command is meant for a static-only setup, and is not necessary to make your application static. Pages in your application without server-side data dependencies will be automatically statically exported by `next build`, including pages powered by `getStaticProps`
 
-#### Possible Ways to Fix It
+## Possible Ways to Fix It
 
 Use `next build` with platforms that don't require `next export` like https://vercel.com or remove any paths using API routes from your `exportPathMap` in `next.config.js`.
 
-### Useful Links
+## Useful Links
 
-- [Static HTML export](https://nextjs.org/docs/advanced-features/static-html-export)
+- [Static HTML export](/docs/pages/building-your-application/deploying/static-exports)

errors/app-container-deprecated.md → errors/app-container-deprecated.mdx

@@ -1,17 +1,19 @@
-# App Container Deprecated
+---
+title: App Container Deprecated
+---
 
-#### Why This Error Occurred
+## Why This Error Occurred
 
 In versions prior to v9.0.4 the `<Container>` component was used in `./pages/_app.js` to handle scrolling to hashes.
 This handling has been moved up the tree so the `<Container>` component is no longer needed in your custom `<App>`!
 
-#### Possible Ways to Fix It
+## Possible Ways to Fix It
 
 Remove the `<Container>` component from your Custom `<App>` (`./pages/_app.js`).
 
 **Before**
 
-```jsx
+```jsx filename="pages/_app.js"
 import React from 'react'
 import App, { Container } from 'next/app'
 
@@ -31,7 +33,7 @@ export default MyApp
 
 **After**
 
-```jsx
+```jsx filename="pages/_app.js"
 import React from 'react'
 import App from 'next/app'
 

errors/app-dir-dynamic-href.md → errors/app-dir-dynamic-href.mdx

@@ -1,14 +1,16 @@
-# Dynamic `href` is not supported in the `/app` directory
+---
+title: 'Dynamic `href` is not supported in the App Router'
+---
 
-#### Why This Error Occurred
+## Why This Error Occurred
 
 You have tried to use a dynamic `href` with `next/link` in the `app` directory. This is not supported as the new client-side router no longer uses a mapping of dynamic routes -> url, instead it always leverages the url.
 
-#### Possible Ways to Fix It
+## Possible Ways to Fix It
 
 **Before**
 
-```jsx
+```jsx filename="app/page.js"
 <Link
   href={{
     pathname: '/route/[slug]',
@@ -21,16 +23,16 @@ You have tried to use a dynamic `href` with `next/link` in the `app` directory.
 
 Or
 
-```jsx
+```jsx filename="app/page.js"
 <Link href="/route/[slug]?slug=1">link</Link>
 ```
 
 **After**
 
-```jsx
+```jsx filename="app/page.js"
 <Link href="/route/1">link</Link>
 ```
 
-### Useful Links
+## Useful Links
 
-[`next/link` documentation](https://beta.nextjs.org/docs/api-reference/components/link#href)
+[`next/link` documentation](/docs/pages/api-reference/components/link#href-required)

errors/app-static-to-dynamic-error.mdx

@@ -0,0 +1,20 @@
+---
+title: 'App Router Static to Dynamic Error'
+---
+
+## Why This Error Occurred
+
+Inside one of your `app/` pages, the page was initially generated statically at build time, and then during runtime either a fallback path or path being revalidated attempted to leverage dynamic server values e.g. `cookies()` or `headers()`.
+
+This is a hard error by default as a path generated statically can't switch between types during runtime currently.
+
+## Possible Ways to Fix It
+
+Prevent usage of these dynamic server values conditionally which can cause the static/dynamic mode of the page to differ between build time and runtime.
+
+Leverage `export const dynamic = 'force-static'` to ensure the page is handled statically regardless of the usage of dynamic server values. Alternatively, if you prefer your page to always be dynamic you can set `export const dynamic = 'force-dynamic'` and it won't attempt to have the page be statically generated.
+
+## Useful Links
+
+- [static/dynamic rendering](/docs/app/building-your-application/rendering/static-and-dynamic-rendering)
+- [dynamic server value methods](/docs/app/building-your-application/rendering/static-and-dynamic-rendering#dynamic-functions)

errors/babel-font-loader-conflict.mdx

@@ -0,0 +1,16 @@
+---
+title: 'Babel and `next/font` conflict'
+---
+
+## Why This Error Occurred
+
+You have tried to use `next/font` with a custom babel config. When your application has a custom babel config you opt-out of the Next.js Compiler which is required to use `next/font`.
+
+## Possible Ways to Fix It
+
+- Remove your custom babel config and use the Next.js Compiler
+
+## Useful Links
+
+- [Next.js Compiler](/docs/architecture/nextjs-compiler)
+- [Customizing Babel Config](/docs/pages/building-your-application/configuring/babel)

errors/beta-middleware.mdx

@@ -0,0 +1,17 @@
+---
+title: Beta Middleware Used
+---
+
+## Why This Error Occurred
+
+[Middleware](/docs/pages/building-your-application/routing/middleware) was beta in versions prior to `v12.2` and not yet covered by [semver](https://semver.org/).
+
+## Possible Ways to Fix It
+
+You can continue to use Middleware in versions prior to `v12.2`. However, you will need to make changes to upgrade to newer versions.
+
+If you're using Next.js on Vercel, your existing deploys using Middleware will continue to work, and you can continue to deploy your site using Middleware. When you upgrade your site to `v12.2` or later, you will need to follow the [upgrade guide](/docs/messages/middleware-upgrade-guide).
+
+## Useful Links
+
+- [Middleware Upgrade Guide](/docs/messages/middleware-upgrade-guide)

errors/build-dir-not-writeable.mdx

@@ -0,0 +1,32 @@
+---
+title: Build directory not writeable
+---
+
+## Why This Error Occurred
+
+The filesystem does not allow writing to the specified directory. A common cause for this error is starting a [custom server](/docs/pages/building-your-application/configuring/custom-server) in development mode on a production server, for example, [Vercel](https://vercel.com) which doesn't allow you to write to the filesystem after your app is built.
+
+## Possible Ways to Fix It
+
+When using a custom server with a server file, for example called `server.js`, make sure you update the scripts key in `package.json` to:
+
+```json filename="package.json"
+{
+  "scripts": {
+    "dev": "node server.js",
+    "build": "next build",
+    "start": "NODE_ENV=production node server.js"
+  }
+}
+```
+
+and the custom server starts Next in production mode when `NODE_ENV` is `production`
+
+```js filename="server.js"
+const dev = process.env.NODE_ENV !== 'production'
+const app = next({ dev })
+```
+
+## Useful Links
+
+- [Custom Server documentation + examples](/docs/pages/building-your-application/configuring/custom-server)