Upgrading from Nextra v2 to Nextra v3: A "Quick" Guide

Nextra, a powerful framework built on top of Next.js, has been empowering developers to create content-focused websites effortlessly.

It is a valid homemade alternative to services like Mintlify.

This blog post will guide you through the process of upgrading from Nextra v2 to Nextra v3, focusing on the nextra-theme-docs.

Official and Comprehensive Release Notes

If you want to learn more about version 3, including all the changes and improvements made, check out the official announcement here.

Below is a quick step-by-step guide

Step 1: Update Your Packages

The first step in upgrading to Nextra v3 is to update your packages. This can be quickly done using the following command:

pnpm up nextra@latest nextra-theme-docs@latest

This command ensures that you have the latest versions of Nextra and nextra-theme-docs, allowing you to leverage all the new features and improvements.

Step 2: Update Your next.config.js

In Nextra v3, there are some changes to how the configuration file is structured. If you were using next.config.js in the following format:

const withNextra = require('nextra')({

  theme: 'nextra-theme-docs',

  themeConfig: './theme.config.tsx',

})

module.exports = withNextra()

You will need to rename the file to next.config.mjs and update it as follows:

import nextra from 'nextra'

const withNextra = nextra({
  theme: 'nextra-theme-docs',
  themeConfig: './theme.config.tsx',
  latex: true,
  search: {
    codeblocks: false
  }
})

export default withNextra({
  reactStrictMode: true
})

This update not only changes the import syntax to ES module format but also introduces new options like latex and search configurations.

Step 3: Rename _app.mdx

If your project includes an _app.mdx file, you must rename it to _app.tsx. Additionally, check your tsconfig.json and update the include section to reflect this change:

"include": [
  "next-env.d.ts",
  "**/*.ts",
  "**/*.tsx",
  // "pages/_app.mdx" <-- remove
  "pages/_app.tsx"
]

This ensures that TypeScript compiles the correct files and avoids any potential errors during the build process.

Step 4: Update theme.config.tsx

The theme configuration has remained mostly the same in Nextra v3. However, if you have used the banner feature, you need to update the text property to content:

banner: {
  key: "v1-6-5-released",

  // text: <a href="/docs/release-notes">🎉 v1.6.5 Released →</a>,

  content: <a href="/docs/release-notes">🎉 v1.6.5 Released →</a>,
}

This minor change ensures compatibility with the new version.

Step 5: Update _meta.json Files

One of the more tedious tasks in upgrading to Nextra v3 is updating the _meta.json files. These files have transitioned from JSON to JS or TS formats. This requires renaming the files and converting the JSON content to JavaScript objects. Here's an example of how to perform this conversion:

Before (JSON):

{
  "console": "Extra Console",
  "writing-commands": "Writing Commands"
}

After (TypeScript):

export default {
  "console": "Extra Console",
  "writing-commands": "Writing Commands",
};

For those with many files to convert, consider using automation tools or writing scripts to streamline the process. One such tool is Raycast, which can be customized to automate these conversions. The prompt example used in Raycast for this conversion is:

As Typescript expert, convert the JSON in a Typescript Object.
-  Export as default directly without create a variabile.
-  Do not add any comments to your answer, just show the response without an introduction.
-  Return the RAW test without using markdown wrapper

JSON:{selection}

Typescript Object:

Step 6: Update MDX Documentation Files

In Nextra v3, components like Cards and Card have undergone changes. If you've used these components, update your imports and implementation as follows:

Before:

import { Callout, Card, Cards, FileTree } from 'nextra/components'

After:

import { Callout, Cards, FileTree } from 'nextra/components'

And for implementation:

Before:

<Cards>
  <Card title="Plugin Class" ... />
</Cards>

After:

<Cards>
  <Cards.Card title="Plugin Class" ... />
</Cards>

These changes ensure that your documentation files are compatible with the new version and benefit from the latest enhancements.

Conclusion

Upgrading from Nextra v2 to Nextra v3 is a straightforward process that brings many benefits, including improved performance and new features. By following these steps, you can ensure a smooth transition and take full advantage of what Nextra v3 offers. As Nextra continues to evolve, with version 4 already in pre-release, staying updated will help you maintain a cutting-edge content-focused website.

If you encounter any issues during the upgrade or have suggestions for improvement, feel free to reach out. The community is always here to help, and your feedback is invaluable in shaping the future of Nextra.

Happy coding!