docs: add Next.js Deno build troubleshooting (#3395)

Author: avocet-bot

deploy/reference/frameworks.md

@@ -1,5 +1,5 @@
 ---
-last_modified: 2026-02-11
+last_modified: 2026-07-07
 title: Frameworks
 description: "Detailed guide to supported JavaScript and TypeScript frameworks in Deno Deploy, including Next.js, Astro, Nuxt, SvelteKit, and more."
 ---
@@ -40,6 +40,50 @@ Next.js on Deno Deploy always builds in standalone mode.
 Tracing is supported out of the box, and Next.js automatically emits some spans
 for incoming requests, routing, rendering, and other operations.
 
+#### Deno compatibility notes
+
+Next.js projects run on Deno Deploy through Deno's Node and npm compatibility
+layer. Most Next.js apps work without extra changes, but the following issues
+can show up in projects generated by scaffolding tools or coding agents:
+
+- Prefer `next.config.mjs` with `export default` for the broadest Next.js
+  version compatibility. If you are using Next.js 15 or newer, `next.config.ts`
+  with `export default` is also supported. Deno's `detect-cjs` option helps
+  CommonJS `next.config.js` files, but some Next.js versions and loaders can
+  still report a "module is not defined" error when a config is loaded as ESM.
+  Using an ESM config avoids that ambiguity.
+- Some Next.js versions can crash during the lint/type-check phase under Deno
+  with `Cannot read properties of undefined (reading 'bold')`. Until this is
+  fixed upstream, you can unblock the build by setting
+  `typescript.ignoreBuildErrors` and `eslint.ignoreDuringBuilds` in your Next.js
+  config. Because this skips Next.js's build-time checks, keep running type
+  checking and linting separately in CI.
+- App Router pages are still prerendered at build time when Next.js decides they
+  are static. If a client component calls browser-only hooks or APIs, defer that
+  code until after the component mounts, such as in `useEffect`. If you need to
+  disable SSR with `next/dynamic` and `{ ssr: false }`, put the dynamic import
+  in a Client Component wrapper; Server Components cannot use `{ ssr: false }`
+  directly. Marking the route dynamic is not enough: dynamic routes still render
+  on the server, where browser globals are undefined.
+
+Example `next.config.mjs`:
+
+```js title="next.config.mjs"
+/** @type {import('next').NextConfig} */
+const nextConfig = {
+  typescript: {
+    // Workaround for known Next.js-on-Deno build-time type-check crashes.
+    ignoreBuildErrors: true,
+  },
+  eslint: {
+    // Keep linting in CI while allowing `next build` to complete on Deno.
+    ignoreDuringBuilds: true,
+  },
+};
+
+export default nextConfig;
+```
+
 ### Astro (`astro`)
 
 Astro is a web framework for building content-driven websites like blogs,

examples/tutorials/next.md

@@ -1,5 +1,5 @@
 ---
-last_modified: 2026-06-16
+last_modified: 2026-07-07
 title: "Build a Next.js App"
 description: "Walkthrough guide to building a Next.js application with Deno. Learn how to set up a project, create API routes, implement server-side rendering, and build a full-stack TypeScript application."
 url: /examples/next_tutorial/
@@ -57,6 +57,23 @@ compatibility, update your `deno.json` file with the following configuration:
 }
 ```
 
+Next.js reads `next.config.*` during local and Deploy builds. With Deno, prefer
+an ESM config file named `next.config.mjs`. Current Next.js releases also
+support `next.config.ts` with the same `export default` shape:
+
+```js title="next.config.mjs"
+/** @type {import('next').NextConfig} */
+const nextConfig = {};
+
+export default nextConfig;
+```
+
+If you started from a scaffold that generated `next.config.js` with
+`module.exports`, Deno's `detect-cjs` option usually lets that CommonJS config
+work. If you still see `module is not defined`, or if a tool loads the config as
+an ES module, rename it to `next.config.mjs` and use `export default` as shown
+above.
+
 Now install the dependencies found in the package.json:
 
 ```sh
@@ -178,9 +195,9 @@ export type Dino = { name: string; description: string };
 We'll update the `page.tsx` file in the `app` directory to fetch the dinosaur
 data from our API and display it as a list of links.
 
-To execute client-side code in Next.js we need to use the `use Client` directive
-at the top of the file. Then we'll import the modules that we'll need in this
-page and export the default function that will render the page:
+To execute client-side code in Next.js we need to use the `"use client"`
+directive at the top of the file. Then we'll import the modules that we'll need
+in this page and export the default function that will render the page:
 
 ```tsx title="page.tsx"
 "use client";
@@ -302,6 +319,24 @@ details!
 Now that you have your working Next.js app, you can deploy it to the web with
 Deno Deploy.
 
+:::tip Build troubleshooting
+
+If `next build` fails on Deno with
+`Cannot read properties of undefined (reading 'bold')`, the failure is in
+Next.js's build-time lint/type-check pass. A temporary workaround is to add
+`typescript.ignoreBuildErrors` and `eslint.ignoreDuringBuilds` to
+`next.config.mjs`, then run type checking and linting separately in CI.
+
+If a client component uses browser-only hooks or APIs, Next.js may still try to
+render it on the server during prerendering or SSR. Defer that code until after
+the component mounts, such as in `useEffect`. If you need to disable SSR with
+`next/dynamic` and `{ ssr: false }`, put the dynamic import in a Client
+Component wrapper; Server Components cannot use `{ ssr: false }` directly.
+Marking the route dynamic alone is not enough because dynamic routes still
+render on the server, where browser globals are undefined.
+
+:::
+
 For the best experience, you can deploy your app directly from GitHub, which
 will set up automated deployments. Create a GitHub repository and push your app
 there.