Docs: Conflicting information about `.mts` support in Next.js config files

[zigang93]

What is the documentation issue?

Description

There’s a contradiction in the Next.js documentation regarding the use of .mts for configuration files.

📄 References

1. ECMAScript Modules section
   https://nextjs.org/docs/app/api-reference/config/next-config-js#ecmascript-modules

   “Good to know: next.config with the .cjs, .cts, or .mts extensions are currently not supported.”

2. TypeScript configuration section
   https://nextjs.org/docs/app/api-reference/config/typescript#for-commonjs-projects-default

   “Therefore, we recommend using the next.config.mts file for CommonJS projects to explicitly indicate it’s an ESM module.”

⚠️ Problem

• The first page says .mts is not supported for next.config.
• The second page recommends using .mts for TypeScript projects.
• This leaves readers unsure whether .mts is officially supported or not.

This inconsistency is confusing, especially for developers working with TypeScript and ESM/CommonJS interop.

🙏 Thank you

Thank you for maintaining great documentation — just hoping to clarify this inconsistency to help others avoid confusion!

Is there any context that might help us understand?

✅ Suggested Fix

• Clarify whether .mts is actually supported for next.config.
• If it is supported:
  • Update the “not supported” warning to explain the specific context where it’s allowed (e.g., TypeScript + ESM).
• If it is not supported:
  • Remove or reword the .mts recommendation from the TypeScript docs.
• Consider adding a table summarizing which extensions are supported per environment:

  File Type	CommonJS	ESM	Notes
  next.config.js	✅	✅	Default
  next.config.mjs	❌	✅	For ESM projects
  next.config.cjs	✅	❌	For CommonJS projects
  next.config.ts	✅	✅	TypeScript version
  next.config.mts	❓	❓	Clarify status

💻 Environment (for context)

• Next.js version: Latest (as of November 2025)
• Node.js: v24
• TypeScript project using "type": "module"
• Tried both next.config.ts and next.config.mts

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

https://nextjs.org/docs/app/api-reference/config/next-config-js#ecmascript-modules

[github-actions]

This closed issue has been automatically locked because it had no new activity for 2 weeks. If you are running into a similar issue, please create a new issue with the steps to reproduce. Thank you.