Issue Station
Sign In
Tools hereToolbox

nextjs - ✅(Solved) Fix Docs: Need to update next.config.js example to use ESM + support TS/.mjs [1 pull requests, 4 comments, 2 participants]

Official PRs (…)
ON THIS PAGE

Recommended Tools

×6

Utilities matched from this issue’s tags and category — try them while you read without losing context.

GitHub issue graph ai analysis

Paste a GitHub issue URL. We fetch that issue, discover linked issues from bodies/comments/timeline, collect linked pull requests, and produce a structured English report.

The report is written in English Markdown for sharing and archival.

Helpful · Quick feedback

Loading…
GitHub stats
vercel/next.js#84017•Fetched 2026-04-08 02:20:55
View on GitHub
Comments
4
Participants
2
Timeline
14
Reactions
0
Author
coderrshyamcoderrshyam
Participants
coderrshyamcoderrshyamYash-AinapureYash-Ainapure
Timeline (top)
commented ×4mentioned ×4subscribed ×4cross-referenced ×1

Root Cause

Keeps docs consistent with modern Next.js defaults (ESM).

Makes it clearer for new users who may otherwise copy outdated CommonJS syntax.

Improves discoverability for TypeScript users.

Note:- This issue is associated with many documentation, the base url for this all documentation is https://nextjs.org/docs/app/api-reference/config/next-config-js.

Fix Action

Fixed

PR fix notes

PR #84046: docs(config): update next.config examples to ESM and add TS #84017

Description (problem / solution / changelog)

What? This PR updates all next.config.js code examples within the App Router API reference to use modern syntax. The changes convert the examples from CommonJS to ESM (.mjs) and add a corresponding TypeScript (.ts) version with an interactive toggle.

Why? The existing documentation used outdated CommonJS (module.exports) syntax, while the official Next.js recommendation is to use ESM (export default). Additionally, the code examples lacked TypeScript versions and proper line highlighting, which are crucial for developer experience. This change brings the documentation in line with modern best practices.

How? Iterated through all .mdx files in the /docs/app/api-reference/config/next-config-js/ directory.

Replaced the old single code block with two consecutive blocks using the switcher prop to create the TS/JS toggle.

Added the highlight prop to each example to emphasize the relevant configuration option.

Updated surrounding prose (e.g., next.config.js -> next.config.mjs) to maintain consistency.

Fixes #84017

Changed files

  • docs/01-app/03-api-reference/05-config/01-next-config-js/allowedDevOrigins.mdx (modified, +18/-3)
  • docs/01-app/03-api-reference/05-config/01-next-config-js/assetPrefix.mdx (modified, +16/-2)
  • docs/01-app/03-api-reference/05-config/01-next-config-js/authInterrupts.mdx (modified, +8/-3)
  • docs/01-app/03-api-reference/05-config/01-next-config-js/basePath.mdx (modified, +18/-3)
  • docs/01-app/03-api-reference/05-config/01-next-config-js/browserDebugInfoInTerminal.mdx (modified, +15/-9)
  • docs/01-app/03-api-reference/05-config/01-next-config-js/cacheComponents.mdx (modified, +13/-2)
  • docs/01-app/03-api-reference/05-config/01-next-config-js/cacheLife.mdx (modified, +8/-3)
  • docs/01-app/03-api-reference/05-config/01-next-config-js/compress.mdx (modified, +17/-2)
  • docs/01-app/03-api-reference/05-config/01-next-config-js/crossOrigin.mdx (modified, +17/-2)
  • docs/01-app/03-api-reference/05-config/01-next-config-js/cssChunking.mdx (modified, +9/-7)
  • docs/01-app/03-api-reference/05-config/01-next-config-js/distDir.mdx (modified, +18/-3)
  • docs/01-app/03-api-reference/05-config/01-next-config-js/env.mdx (modified, +20/-3)
  • docs/01-app/03-api-reference/05-config/01-next-config-js/expireTime.mdx (modified, +19/-3)
  • docs/01-app/03-api-reference/05-config/01-next-config-js/exportPathMap.mdx (modified, +47/-6)
  • docs/01-app/03-api-reference/05-config/01-next-config-js/generateBuildId.mdx (modified, +21/-3)
  • docs/01-app/03-api-reference/05-config/01-next-config-js/generateEtags.mdx (modified, +18/-3)
  • docs/01-app/03-api-reference/05-config/01-next-config-js/headers.mdx (modified, +420/-19)
  • docs/01-app/03-api-reference/05-config/01-next-config-js/htmlLimitedBots.mdx (modified, +7/-2)
  • docs/01-app/03-api-reference/05-config/01-next-config-js/httpAgentOptions.mdx (modified, +20/-3)
  • docs/01-app/03-api-reference/05-config/01-next-config-js/images.mdx (modified, +307/-24)
  • docs/01-app/03-api-reference/05-config/01-next-config-js/index.mdx (modified, +76/-17)
  • docs/01-app/03-api-reference/05-config/01-next-config-js/inlineCss.mdx (modified, +5/-3)
  • docs/01-app/03-api-reference/05-config/01-next-config-js/logging.mdx (modified, +99/-10)
  • docs/01-app/03-api-reference/05-config/01-next-config-js/mdxRs.mdx (modified, +20/-4)
  • docs/01-app/03-api-reference/05-config/01-next-config-js/onDemandEntries.mdx (modified, +23/-3)
  • docs/01-app/03-api-reference/05-config/01-next-config-js/optimizePackageImports.mdx (modified, +19/-2)
  • docs/01-app/03-api-reference/05-config/01-next-config-js/output.mdx (modified, +119/-16)
  • docs/01-app/03-api-reference/05-config/01-next-config-js/pageExtensions.mdx (modified, +53/-10)
  • docs/01-app/03-api-reference/05-config/01-next-config-js/poweredByHeader.mdx (modified, +18/-3)
  • docs/01-app/03-api-reference/05-config/01-next-config-js/productionBrowserSourceMaps.mdx (modified, +17/-2)
  • docs/01-app/03-api-reference/05-config/01-next-config-js/reactCompiler.mdx (modified, +11/-7)
  • docs/01-app/03-api-reference/05-config/01-next-config-js/reactMaxHeadersLength.mdx (modified, +18/-3)
  • docs/01-app/03-api-reference/05-config/01-next-config-js/reactStrictMode.mdx (modified, +18/-3)
  • docs/01-app/03-api-reference/05-config/01-next-config-js/redirects.mdx (modified, +356/-19)
  • docs/01-app/03-api-reference/05-config/01-next-config-js/rewrites.mdx (modified, +504/-33)
  • docs/01-app/03-api-reference/05-config/01-next-config-js/sassOptions.mdx (modified, +5/-4)
  • docs/01-app/03-api-reference/05-config/01-next-config-js/serverActions.mdx (modified, +58/-10)
  • docs/01-app/03-api-reference/05-config/01-next-config-js/serverComponentsHmrCache.mdx (modified, +6/-4)
  • docs/01-app/03-api-reference/05-config/01-next-config-js/serverExternalPackages.mdx (modified, +15/-3)
  • docs/01-app/03-api-reference/05-config/01-next-config-js/staleTimes.mdx (modified, +20/-3)
  • docs/01-app/03-api-reference/05-config/01-next-config-js/staticGeneration.mdx (modified, +1/-1)
  • docs/01-app/03-api-reference/05-config/01-next-config-js/taint.mdx (modified, +14/-12)
  • docs/01-app/03-api-reference/05-config/01-next-config-js/trailingSlash.mdx (modified, +18/-3)
  • docs/01-app/03-api-reference/05-config/01-next-config-js/transpilePackages.mdx (modified, +15/-3)
  • docs/01-app/03-api-reference/05-config/01-next-config-js/turbopack.mdx (modified, +105/-15)
  • docs/01-app/03-api-reference/05-config/01-next-config-js/typedRoutes.mdx (modified, +15/-3)
  • docs/01-app/03-api-reference/05-config/01-next-config-js/typescript.mdx (modified, +24/-3)
  • docs/01-app/03-api-reference/05-config/01-next-config-js/urlImports.mdx (modified, +20/-3)
  • docs/01-app/03-api-reference/05-config/01-next-config-js/useLightningcss.mdx (modified, +5/-3)
  • docs/01-app/03-api-reference/05-config/01-next-config-js/viewTransition.mdx (modified, +17/-5)
  • docs/01-app/03-api-reference/05-config/01-next-config-js/webVitalsAttribution.mdx (modified, +18/-3)
  • docs/01-app/03-api-reference/05-config/01-next-config-js/webpack.mdx (modified, +50/-8)

Code Example

// next.config.js
module.exports = {
  allowedDevOrigins: ['local-origin.dev'],
}

---
RAW_BUFFERClick to expand / collapse

What is the documentation issue?

In the Next.js documentation, the configuration examples currently show CommonJS syntax with .js extension.

example: https://nextjs.org/docs/app/api-reference/config/next-config-js/allowedDevOrigins

// next.config.js
module.exports = {
  allowedDevOrigins: ['local-origin.dev'],
}

Problems

  1. CommonJS instead of ESM The docs still show module.exports.

Next.js officially recommends ESM (export default) for config files.

  1. No TypeScript dropdown

Unlike many other code examples in the docs, there’s no dropdown to switch to TypeScript (next.config.ts).

  1. Wrong file extension

For ESM configs, the file should be next.config.mjs, not .js.

  1. Missing highlight

The most important line should be highlighted to guide readers. For above codeblock the highlighted line should be allowedDevOrigins: ['local-origin.dev'],.

Is there any context that might help us understand?

Suggested Fix

Update the docs to use ESM by default, add a TS dropdown, and highlight the critical line.

Example:

// next.config.mjs
/** 
 * @type {import('next').NextConfig}
 */
const nextConfig = {
  allowedDevOrigins: ['local-origin.dev'], // highlighted 
}
 
export default nextConfig
// next.config.ts
import type { NextConfig } from 'next'
 
const nextConfig: NextConfig = {
   allowedDevOrigins: ['local-origin.dev'], // highlighted 
}
 
export default nextConfig

With the export default line highlighted.

Why this matters

Keeps docs consistent with modern Next.js defaults (ESM).

Makes it clearer for new users who may otherwise copy outdated CommonJS syntax.

Improves discoverability for TypeScript users.

Note:- This issue is associated with many documentation, the base url for this all documentation is https://nextjs.org/docs/app/api-reference/config/next-config-js.

Does the docs page already exist? Please link to it.

https://nextjs.org/docs/app/api-reference/config/next-config-js/*

extent analysis

TL;DR

Update the Next.js documentation to use ESM syntax by default, add a TypeScript dropdown, and highlight the critical line in code examples.

Guidance

  • Update configuration examples to use ESM syntax (export default) instead of CommonJS (module.exports).
  • Add a TypeScript dropdown to allow users to switch between JavaScript and TypeScript examples.
  • Use the correct file extension for ESM configs (next.config.mjs instead of next.config.js).
  • Highlight the most important line in code examples to guide readers.

Example

// next.config.mjs
/** 
 * @type {import('next').NextConfig}
 */
const nextConfig = {
  allowedDevOrigins: ['local-origin.dev'], // highlighted 
}
 
export default nextConfig

Notes

This fix applies to all documentation pages under the base URL https://nextjs.org/docs/app/api-reference/config/next-config-js.

Recommendation

Apply workaround: Update the documentation to use ESM syntax and add a TypeScript dropdown to improve consistency and discoverability for users.

Vote matrix · Quick signals

Works
Did the solution work? Tap to confirm.
Easy Fix
Was it a quick fix?
Time Saver
Did it save you time?
Blocking
Was it severely blocking?
Common Issue
Are others likely hitting this too?
Flaky / Intermittent
Is it intermittent?
Verified / Reproducible
Can you reproduce it reliably?
Loading…
#api#ssr#memory leak#API versioning#request timeout

Still need to ship something?

×6

Another batch ranked right after the header list — different links, same matching logic.

Back to top recommendations

TRENDING