vercel / vercel/next.js

Docs: Need to update next.config.js example to use ESM + support TS/.mjs

Open
#84,017 4 comments 0 reactions 0 assignees View on GitHub

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

  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/*

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.