[v3] bundle to ESM only, use next.config.mjs or next.config.js wi…

…th `"type": "module"` (#2254)

.changeset/mighty-cars-hear.md

@@ -8,4 +8,4 @@
 
 - remove `Card` export, use `Cards.Card` instead
 
-- disallow import md/mdx files that are outside of the working directory, use symlinks instead
+- disallow import md/mdx files that are outside the working directory, use symlinks instead

.changeset/moody-pianos-hide.md

@@ -0,0 +1,7 @@
+---
+'nextra': major
+---
+
+**BREAKING** bundle to ESM only
+
+> ⚠️⚠️⚠️ use `next.config.mjs` or `next.config.js` with `"type": "module"`

docs/pages/docs/blog-theme/start.mdx

@@ -33,18 +33,20 @@ npm i next react react-dom nextra nextra-theme-blog
 
 ### Add Next.js Config
 
-Create the following `next.config.js` file in your project’s root directory:
+Create the following `next.config.mjs` file in your project’s root directory:
 
-```js filename="next.config.js"
-const withNextra = require('nextra')({
+```js filename="next.config.mjs"
+import nextra from 'nextra'
+
+const withNextra = nextra({
   theme: 'nextra-theme-blog',
   themeConfig: './theme.config.jsx'
 })
 
-module.exports = withNextra()
+export default withNextra()
 
 // If you have other Next.js configurations, you can pass them as the parameter:
-// module.exports = withNextra({ /* other next.js config */ })
+// export default withNextra({ /* other next.js config */ })
 ```
 
 With the above configuration, Nextra can handle Markdown files in your Next.js

docs/pages/docs/custom-theme.mdx

@@ -21,15 +21,15 @@ First, you need to tell Nextra to use your custom theme file instead of official
 ones. In your Next.js config, you can pass the path to your theme file to the
 Nextra plugin:
 
-```js {2} filename="next.config.js"
-const withNextra = require('nextra')({
-  theme: './theme.tsx',
-})
+```js {4} filename="next.config.mjs"
+import nextra from 'nextra'
 
-module.exports = withNextra({
-  // Other Next.js configurations
-  ...
+const withNextra = nextra({
+  theme: './theme.tsx'
 })
+
+// If you have other Next.js configurations, you can pass them as the parameter:
+// export default withNextra({ /* other next.js config */ })
 ```
 
 ### Create a Basic Theme

docs/pages/docs/docs-theme/start.mdx

@@ -54,18 +54,20 @@ npm i next react react-dom nextra nextra-theme-docs
 
 ### Add Next.js Config
 
-Create the following `next.config.js` file in your project’s root directory:
+Create the following `next.config.mjs` file in your project’s root directory:
 
-```js filename="next.config.js"
-const withNextra = require('nextra')({
+```js filename="next.config.mjs"
+import nextra from 'nextra'
+
+const withNextra = nextra({
   theme: 'nextra-theme-docs',
   themeConfig: './theme.config.jsx'
 })
 
-module.exports = withNextra()
+export default withNextra()
 
 // If you have other Next.js configurations, you can pass them as the parameter:
-// module.exports = withNextra({ /* other next.js config */ })
+// export default withNextra({ /* other next.js config */ })
 ```
 
 With the above configuration, Nextra can handle Markdown files in your Next.js

docs/pages/docs/get-started.mdx.backup

@@ -19,13 +19,15 @@ Nextra works like a Next.js plugin, and it accepts a theme config (layout) to re
 
 3. Create the following Next.js config:
 
-```js filename="next.config.js"
-const withNextra = require('nextra')({
+```js filename="next.config.mjs"
+import nextra from 'nextra'
+
+const withNextra = nextra({
   theme: 'nextra-theme-docs',
   themeConfig: './theme.config.jsx'
   // optional: add `staticImage: true` to enable Nextra's auto image import
 })
-module.exports = withNextra()
+export default withNextra()
 ```
 
 4. Create a `theme.config.jsx` file for the docs theme:

docs/pages/docs/guide/advanced/latex.mdx

@@ -1,12 +1,16 @@
 # LaTeX
 
 Nextra uses [KaTeX](https://katex.org/) to render LaTeX expressions directly in MDX.
-To enable LaTeX support, you must enable the `latex` option in your `next.config.js` file:
+To enable LaTeX support, you must enable the `latex` option in your `next.config.mjs` file:
 
-```js filename="next.config.js"
-module.exports = require('nextra')({
+```js filename="next.config.mjs"
+import nextra from 'nextra'
+
+const withNextra = nextra({
   latex: true
 })
+
+export default withNextra()
 ```
 
 When enabled, KaTeX’s CSS and fonts will be automatically included in your site, and you can start writing math expressions in your MDX files. Using LaTeX within MDX is as simple as wrapping your expression in `$` or `$$`.

docs/pages/docs/guide/i18n.mdx

@@ -12,15 +12,17 @@ out of the box. These docs explain how to configure and use it.
 ### Add I18n Config
 
 To add multi-language pages to your Nextra application, you need to config
-`i18n` in `next.config.js` first:
+`i18n` in `next.config.mjs` first:
 
-```js filename="next.config.js" {7-10}
-const withNextra = require('nextra')({
+```js filename="next.config.mjs" {9-12}
+import nextra from 'nextra'
+
+const withNextra = nextra({
   theme: 'nextra-theme-docs',
   themeConfig: './theme.config.tsx'
 })
 
-module.exports = withNextra({
+export default withNextra({
   i18n: {
     locales: ['en', 'zh', 'de'],
     defaultLocale: 'en'

docs/pages/docs/guide/syntax-highlighting.mdx

@@ -103,7 +103,7 @@ console.log('hello, world')
 ```
 
 You can enable this feature globally by setting `defaultShowCopyCode: true` in
-your Nextra configuration (`next.config.js` file). Once it's enabled globally,
+your Nextra configuration (`next.config.mjs` file). Once it's enabled globally,
 you can disable it via the `copy=false` attribute.
 
 ### Line Numbers
@@ -293,7 +293,7 @@ to see how it works.
 
 You can opt out of syntax highlighting for using one of your own. You can
 disable syntax highlighting globally by setting `codeHighlight: false` in your
-Nextra configuration (`next.config.js` file).
+Nextra configuration (`next.config.mjs` file).
 
 <OptionTable
   options={[
@@ -313,9 +313,9 @@ for syntax highlighting with custom language grammars.
 
 You can provide these grammars by overriding the `getHighlighter` function in
 `mdxOptions.rehypePrettyCodeOptions` option in your Nextra config inside
-`next.config.js`:
+`next.config.mjs`:
 
-```js filename="next.config.js" {13-18}
+```js filename="next.config.mjs" {13-18}
 import { BUNDLED_LANGUAGES } from 'shiki'
 
 nextra({
@@ -346,7 +346,7 @@ nextra({
 Within `mdxOptions.rehypePrettyCodeOptions` you may also provide custom themes
 instead of [relying on CSS Variables](/docs/guide/syntax-highlighting):
 
-```js filename="next.config.js" {4}
+```js filename="next.config.mjs" {4}
 nextra({
   // ... other options
   mdxOptions: {

examples/docs/src/pages/features/i18n.mdx

@@ -11,12 +11,17 @@ Nextra supports
 out of the box.
 
 To add multi-language pages to your Nextra application, just need to config
-`i18n` in `next.config.js`:
+`i18n` in `next.config.mjs`:
 
-```js filename="next.config.js"
-const withNextra = require('nextra')('nextra-theme-docs', './theme.config.js')
+```js filename="next.config.mjs"
+import nextra from 'nextra'
 
-module.exports = withNextra({
+const withNextra = nextra({
+  theme: 'nextra-theme-docs',
+  themeConfig: './theme.config.js'
+})
+
+export default withNextra({
   i18n: {
     locales: ['en', 'zh', 'de'],
     defaultLocale: 'en'

examples/docs/src/pages/features/latex.mdx

@@ -2,12 +2,16 @@
 
 Nextra uses [KaTeX](https://katex.org/) to render LaTeX expressions directly in
 MDX. To enable LaTeX support, you must add the following to your
-`next.config.js`:
+`next.config.mjs`:
 
-```js filename="next.config.js"
-module.exports = require('nextra')({
+```js filename="next.config.mjs"
+import nextra from 'nextra'
+
+const withNextra = nextra({
   latex: true
 })
+
+export default withNextra()
 ```
 
 Using LaTeX within MDX is as simple as wrapping your expression in `$$` or `$`.

examples/docs/src/pages/get-started.mdx

@@ -33,13 +33,15 @@ npm i nextra-theme-docs
 
 ### Create the following Next.js config and theme config under the root directory
 
-```js filename="next.config.js"
-const withNextra = require('nextra')({
+```js filename="next.config.mjs"
+import nextra from 'nextra'
+
+const withNextra = nextra({
   theme: 'nextra-theme-blog',
   themeConfig: './theme.config.js'
   // optional: add `staticImage: true` to enable Nextra's auto image import
 })
-module.exports = withNextra()
+export default withNextra()
 ```
 
 ### Create a `theme.config.js` file for the docs theme

examples/docs/src/pages/themes/blog/index.mdx

@@ -19,13 +19,15 @@ commands:
 3. Create the following Next.js config and theme config under the root
    directory:
 
-```js filename="next.config.js"
-const withNextra = require('nextra')({
+```js filename="next.config.mjs"
+import nextra from 'nextra'
+
+const withNextra = nextra({
   theme: 'nextra-theme-blog',
   themeConfig: './theme.config.js'
   // optional: add `staticImage: true` to enable Nextra's auto image import
 })
-module.exports = withNextra()
+export default withNextra()
 ```
 
 ```jsx filename="theme.config.js"

examples/docs/src/pages/themes/docs/configuration.mdx

@@ -580,15 +580,17 @@ Enable Nextra built-in search
 
 **Example:**
 
-```js filename="next.config.js"
-const withNextra = require('nextra')({
+```js filename="next.config.mjs"
+import nextra from 'nextra'
+
+const withNextra = nextra({
   theme: 'nextra-theme-blog',
   themeConfig: './theme.config.js',
   flexsearch: {
     codeblock: false
   }
 })
-module.exports = withNextra()
+export default withNextra()
 ```
 
 <Unstable />

examples/docs/src/pages/themes/docs/index.mdx

@@ -24,13 +24,15 @@ npm i nextra-theme-docs
 
 ### Create the following Next.js config and theme config under the root directory:
 
-```jsx filename="next.config.js"
-const withNextra = require('nextra')({
+```jsx filename="next.config.mjs"
+import nextra from 'nextra'
+
+const withNextra = nextra({
   theme: 'nextra-theme-blog',
   themeConfig: './theme.config.js'
   // optional: add `staticImage: true` to enable Nextra's auto image import
 })
-module.exports = withNextra()
+export default withNextra()
 ```
 
 ```jsx filename="theme.config.js"

packages/nextra/package.json

@@ -7,10 +7,9 @@
   "engines": {
     "node": ">=18"
   },
-  "main": "./dist/index.js",
   "exports": {
     "./package.json": "./package.json",
-    ".": "./dist/index.js",
+    ".": "./dist/index.mjs",
     "./catch-all": "./dist/catch-all.js",
     "./data": {
       "import": "./dist/data.js",
@@ -58,7 +57,7 @@
       "types": "./dist/*.d.mts"
     }
   },
-  "types": "./dist/types.d.mts",
+  "types": "./dist/index.d.mts",
   "typesVersions": {
     "*": {
       "compile": [
@@ -129,15 +128,15 @@
     "katex": "^0.16.8",
     "lodash.get": "^4.4.2",
     "next-mdx-remote": "^4.2.1",
-    "p-limit": "^3.1.0",
+    "p-limit": "^4.0.0",
     "rehype-katex": "^6.0.3",
     "rehype-pretty-code": "0.9.11",
     "rehype-raw": "^7.0.0",
     "remark-gfm": "^3.0.1",
     "remark-math": "^5.1.1",
     "remark-reading-time": "^2.0.1",
     "shiki": "^0.14.3",
-    "slash": "^3.0.0",
+    "slash": "^5.1.0",
     "title": "^3.5.3",
     "unist-util-remove": "^4.0.0",
     "unist-util-visit": "^5.0.0",

packages/nextra/src/constants.ts

@@ -9,13 +9,13 @@ export const IS_PRODUCTION = process.env.NODE_ENV === 'production'
 
 export const DEFAULT_LOCALE = 'en-US'
 
-export const DEFAULT_CONFIG: Omit<NextraConfig, 'theme'> = {
+export const DEFAULT_CONFIG = {
   staticImage: true,
   flexsearch: {
     codeblocks: true
   },
   codeHighlight: true
-}
+} satisfies Partial<NextraConfig>
 
 export const OFFICIAL_THEMES = ['nextra-theme-docs', 'nextra-theme-blog']
 

packages/nextra/src/env.d.ts

@@ -15,6 +15,6 @@ declare namespace globalThis {
   var __nextra_resolvePageMap: () => Promise<PageMapItem[]>
 }
 
-declare module 'next/dist/compiled/webpack/webpack' {
+declare module 'next/dist/compiled/webpack/webpack.js' {
   export { default as webpack, sources } from 'webpack'
 }