[v3] bundle to ESM only, use next.config.mjs or next.config.js with "type": "module" (#2254)

Author: Dimitri POSTOLOV

Diff for: .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

Diff for: .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"`

Diff for: 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

Diff for: 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

Diff for: 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

Diff for: 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:

Diff for: 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 `$$`.

Diff for: 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'

Diff for: 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: {

Diff for: 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'

Diff for: 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 `$`.

Diff for: 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

Diff for: 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"

Diff for: 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 />

Diff for: 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"

Diff for: 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",

Diff for: 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']
 

Diff for: 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'
 }

Diff for: packages/nextra/src/index.js renamed to packages/nextra/src/index.ts

@@ -1,25 +1,23 @@
 /* eslint-env node */
+import { createRequire } from 'node:module'
+import type { NextConfig } from 'next'
 import {
   DEFAULT_CONFIG,
   DEFAULT_LOCALE,
   DEFAULT_LOCALES,
   MARKDOWN_EXTENSION_REGEX,
   MARKDOWN_EXTENSIONS
 } from './constants'
+import type { Nextra } from './types'
 import { logger } from './utils'
 import { NextraPlugin, NextraSearchPlugin } from './webpack-plugins'
 
 const DEFAULT_EXTENSIONS = ['js', 'jsx', 'ts', 'tsx']
 
-const nextra = (themeOrNextraConfig, themeConfig) =>
-  function withNextra(nextConfig = {}) {
-    const nextraConfig = {
-      ...DEFAULT_CONFIG,
-      ...(typeof themeOrNextraConfig === 'string'
-        ? { theme: themeOrNextraConfig, themeConfig }
-        : themeOrNextraConfig)
-    }
+const require = createRequire(import.meta.url)
 
+const nextra: Nextra = nextraConfig =>
+  function withNextra(nextConfig = {}) {
     const hasI18n = !!nextConfig.i18n?.locales
 
     if (hasI18n) {
@@ -32,13 +30,8 @@ const nextra = (themeOrNextraConfig, themeConfig) =>
     }
     const locales = nextConfig.i18n?.locales || DEFAULT_LOCALES
 
-    const rewrites = async () => {
-      const rules = [
-        {
-          source: '/:path*/_meta',
-          destination: '/404'
-        }
-      ]
+    const rewrites: NextConfig['rewrites'] = async () => {
+      const rules = [{ source: '/:path*/_meta', destination: '/404' }]
 
       if (nextConfig.rewrites) {
         const originalRewrites = await nextConfig.rewrites()
@@ -55,13 +48,13 @@ const nextra = (themeOrNextraConfig, themeConfig) =>
     }
 
     const nextraLoaderOptions = {
+      ...DEFAULT_CONFIG,
       ...nextraConfig,
-      locales,
-      defaultLocale: nextConfig.i18n?.defaultLocale || DEFAULT_LOCALE
+      locales
     }
 
     // Check if there's a theme provided
-    if (!nextraLoaderOptions.theme) {
+    if (!nextraConfig.theme) {
       throw new Error('No Nextra theme found!')
     }
 
@@ -70,7 +63,8 @@ const nextra = (themeOrNextraConfig, themeConfig) =>
       ...(nextConfig.output !== 'export' && { rewrites }),
       ...(hasI18n && {
         env: {
-          NEXTRA_DEFAULT_LOCALE: nextraLoaderOptions.defaultLocale,
+          NEXTRA_DEFAULT_LOCALE:
+            nextConfig.i18n?.defaultLocale || DEFAULT_LOCALE,
           ...nextConfig.env
         },
         i18n: undefined
@@ -84,28 +78,11 @@ const nextra = (themeOrNextraConfig, themeConfig) =>
           config.plugins ||= []
           config.plugins.push(new NextraPlugin({ locales }))
 
-          if (nextraConfig.flexsearch) {
+          if (nextraLoaderOptions.flexsearch) {
             config.plugins.push(new NextraSearchPlugin())
           }
         }
 
-        /* Adds client-side webpack optimization rules for splitting chunks during build-time */
-        if (!options.isServer && config.optimization.splitChunks) {
-          config.optimization.splitChunks.cacheGroups = {
-            ...config.optimization.splitChunks.cacheGroups,
-            ...Object.fromEntries(
-              nextraLoaderOptions.locales.map(locale => [
-                `nextra-page-map-${locale}`,
-                {
-                  test: new RegExp(`nextra-page-map-${locale}`),
-                  name: `nextra-page-map-${locale}`,
-                  enforce: true
-                }
-              ])
-            )
-          }
-        }
-
         const defaultESMAppPath = require.resolve('next/dist/esm/pages/_app.js')
         const defaultCJSAppPath = require.resolve('next/dist/pages/_app.js')
 
@@ -114,8 +91,7 @@ const nextra = (themeOrNextraConfig, themeConfig) =>
           // Resolves ESM _app file instead cjs, so we could import theme.config via `import` statement
           [defaultCJSAppPath]: defaultESMAppPath
         }
-
-        config.module.rules.push(
+        ;(config.module.rules as RuleSetRule[]).push(
           {
             // Match Markdown imports from non-pages. These imports have an
             // issuer, which can be anything as long as it's not empty.
@@ -170,4 +146,13 @@ const nextra = (themeOrNextraConfig, themeConfig) =>
     }
   }
 
-module.exports = nextra
+// TODO: take this type from webpack directly
+type RuleSetRule = {
+  issuer: (value: string) => boolean
+  test: RegExp
+  use: unknown[]
+}
+
+export default nextra
+
+export type * from './types'

Diff for: packages/nextra/src/types.ts

@@ -156,13 +156,9 @@ export type NextraConfig = {
 }
 
 export type Nextra = (
-  ...args: [NextraConfig] | [theme: Theme, themeConfig: string]
+  nextraConfig: NextraConfig
 ) => (nextConfig: NextConfig) => NextConfig
 
-const nextra: Nextra = () => () => ({})
-
-export default nextra
-
 export type ThemeConfig = any | null
 
 export type NextraThemeLayoutProps = {

Diff for: packages/nextra/src/webpack-plugins/nextra-search.ts

@@ -1,8 +1,10 @@
-import { sources, webpack } from 'next/dist/compiled/webpack/webpack'
+import pkg from 'next/dist/compiled/webpack/webpack.js'
 import type { Compiler } from 'webpack'
 import { IS_PRODUCTION } from '../constants'
 import type { SearchData } from '../types'
 
+const { sources, webpack } = pkg
+
 export class NextraSearchPlugin {
   apply(compiler: Compiler) {
     const pluginName = this.constructor.name

Diff for: packages/nextra/src/webpack-plugins/nextra.ts

@@ -1,12 +1,14 @@
 import { join } from 'node:path'
-import { promises as fs } from 'graceful-fs'
+import pkg from 'graceful-fs'
 import type { Compiler } from 'webpack'
 import { CHUNKS_DIR } from '../constants'
 import { PAGES_DIR } from '../file-system'
 import { getDynamicMeta } from '../page-map'
 import { collectFiles } from '../plugin'
 import type { Folder } from '../types'
 
+const fs = pkg.promises
+
 export class NextraPlugin {
   constructor(private config: { locales: string[] }) {}
 

Diff for: packages/nextra/tsup.config.ts

@@ -66,7 +66,7 @@ const sharedConfig = {
 export default defineConfig([
   {
     name: 'nextra',
-    entry: ['src/index.js', 'src/__temp__.js', 'src/catch-all.ts'],
+    entry: ['src/__temp__.js', 'src/catch-all.ts'],
     format: 'cjs',
     dts: false
   },
@@ -76,6 +76,7 @@ export default defineConfig([
       'src/**/*.ts',
       '!src/**/*.d.ts',
       '!src/catch-all.ts',
+      '!src/types.ts',
       ...CLIENT_ENTRY.map(filePath => `!${filePath}`)
     ],
     ...sharedConfig