Docs: Need to update next.config.js example to use ESM + support TS/.mjs
Nobody has claimed this yet.
- Dominant language
- JavaScript
- Stars
- 142k
- Forks
- 32.5k
- Avg merge
- 2d 14h
- Merged PRs (30d)
- 351
Description
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
- CommonJS instead of ESM
The docs still showmodule.exports.
Next.js officially recommends ESM (export default) for config files.
- No TypeScript dropdown
Unlike many other code examples in the docs, there’s no dropdown to switch to TypeScript (next.config.ts).
- Wrong file extension
For ESM configs, the file should be next.config.mjs, not .js.
- 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/*
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start with the allowedDevOrigins page linked in the issue and review the related configuration pages under the provided next-config-js URL. Update the examples to show the requested ESM and TypeScript variants, with the specified line highlighting, then verify that the documentation renders correctly and the examples use the intended config filenames.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- javascript, next.js, typescript
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 3/5
- Estimated time
- 1-2 days
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 48/100