Issue Station
Sign In
Tools hereToolbox

nextjs - ✅(Solved) Fix Docs: Conflicting information about `.mts` support in Next.js config files [1 pull requests, 1 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#85715•Fetched 2026-04-08 02:14:12
View on GitHub
Comments
1
Participants
2
Timeline
10
Reactions
0
Author
zigang93zigang93
Participants
github-actions[bot]github-actions[bot]zigang93zigang93
Timeline (top)
referenced ×4closed ×1commented ×1cross-referenced ×1

Fix Action

Fixed

PR fix notes

PR #85716: docs(next.config): this docs should remove ".mts" is not supported.

Description (problem / solution / changelog)

Fix #85715

Changed files

  • docs/01-app/03-api-reference/05-config/01-next-config-js/index.mdx (modified, +1/-1)
RAW_BUFFERClick to expand / collapse

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 TypeCommonJSESMNotes
    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

extent analysis

TL;DR

The documentation inconsistency regarding the use of .mts for next.config files in Next.js should be resolved by clarifying whether .mts is supported and updating the relevant documentation pages accordingly.

Guidance

  • Review the ECMAScript Modules section and the TypeScript configuration section to identify the contradiction and determine the intended support for .mts files.
  • Consider adding a table to summarize supported file extensions for different environments, as suggested in the issue.
  • If .mts is supported, update the "not supported" warning to explain the specific context where it's allowed.
  • If .mts is not supported, remove or reword the recommendation from the TypeScript documentation.

Example

No code snippet is necessary for this documentation issue, but a sample table to clarify supported file extensions could be:

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

Notes

The resolution of this issue depends on the intended support for .mts files in Next.js, which is currently unclear. The suggested fix and table can help clarify the supported file extensions and resolve the documentation inconsistency.

Recommendation

Apply workaround: Update the documentation to clarify the support for .mts files, and consider adding a table to summarize supported file extensions for different environments. This will help resolve the inconsistency and provide clear guidance for developers.

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#index setup#retrieval issue#search optimization#API routing

Still need to ship something?

×6

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

Back to top recommendations

TRENDING

nextjs - ✅(Solved) Fix Docs: Conflicting information about `.mts` support in Next.js config files [1 pull requests, 1 comments, 2 participants]