Skip to content
Get packs

Guide · Open source

How to use Nextra: setup, build and run a docs site

Updated · written with AI from the project's own documentation and checked against our catalogue data

Nextra is an open-source framework for generating websites, especially documentation sites, from Markdown and MDX files. It is built on Next.js, so it follows the Next.js way of building pages with React. This guide shows how to set up the Nextra repository, build its packages and run the included docs example so you can see it working locally.

Nextrashuding/nextra · ★ 13.9k · MIT

Quick start

  1. 1Enable Corepack. Run corepack enable. If it fails, install the latest Corepack with npm install -g corepack@latest.
  2. 2Install dependencies. Run pnpm install in the Nextra repository to install the project's dependencies.
  3. 3Build the core package. Run pnpm --filter nextra build to build the nextra package.
  4. 4Build the docs theme. Run pnpm --filter nextra-theme-docs build to build the nextra-theme-docs package.
  5. 5Start the example docs. Run pnpm --filter example-docs dev to run examples/docs locally and see changes update.

What you need before you start

Nextra is set up from its source code using the command line. The project uses PNPM Workspaces and Turborepo, and the README asks you to enable Corepack and then install dependencies with pnpm.

You need Node.js and pnpm, which is made available through Corepack.

  • Node.js
  • pnpm (via Corepack)
  • A terminal for running the commands

Install Nextra's dependencies with Corepack and pnpm

First, enable Corepack. If that command fails, the README says to install the latest Corepack with npm. Then install the project's dependencies with pnpm.

  • Run corepack enable to enable Corepack.
  • If it fails, run npm install -g corepack@latest.
  • Run pnpm install to install the project's dependencies.
corepack enable pnpm install

Build the nextra and nextra-theme-docs packages

Nextra is split into packages. The README gives a build command for the core nextra package and another for the nextra-theme-docs theme. To keep building while you edit the core package, the README mentions a watch mode.

  • Build the core package with pnpm --filter nextra build.
  • Use watch mode for the core package with pnpm --filter nextra dev.
  • Build the docs theme with pnpm --filter nextra-theme-docs build.
pnpm --filter nextra build pnpm --filter nextra-theme-docs build

Run the example docs site locally

To see Nextra in action, start the example docs site in examples/docs. The README says changes to that example are re-rendered instantly.

If you change the core or theme packages, you need to rebuild them. Alternatively, run watch mode for Nextra and the theme in separate terminals.

  • Start the example with pnpm --filter example-docs dev.
  • Edit files under example/docs and see the changes re-rendered.
  • After changing core or theme code, rebuild or use watch mode in two terminals.
pnpm --filter example-docs dev

Where to find more detail

The README excerpt used for this guide covers only repository setup and development commands. It does not describe the full list of Nextra features, configuration options or content file structure.

For detailed documentation, use the official homepage at nextra.site.

What people use it for

  • Building a project documentation site from Markdown or MDX files
  • Developing a docs theme or core changes and previewing them on the example docs site
  • Running a Next.js-based content site for a team that already knows React

Frequently asked questions

Is Nextra free to use?

Nextra is released under the MIT licence, according to its repository listing. The MIT licence generally allows use, modification and redistribution, but read the licence file in the repository for the exact terms.

What do I need to install Nextra?

The README lists Node.js and pnpm, which is enabled through Corepack. You then clone the repository, run corepack enable and pnpm install.

Do I need to know Next.js to use Nextra?

Nextra is built on Next.js and keeps its way of building pages with React. Familiarity with Next.js and React will help, because the setup and project files follow those conventions.

Why does corepack enable fail?

The README suggests running npm install -g corepack@latest to install the latest Corepack, then trying corepack enable again.

Can non-developers use Nextra?

Setup uses the command line and project files, so it is aimed at developers. Someone who needs a site without writing code will likely need a different tool.

How does Nextra compare to Docusaurus, VitePress or Astro Starlight?

The source material does not include a comparison, so this guide cannot say which is better. Nextra is built on Next.js, while the others are separate frameworks, so choose based on your team's existing tools.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

Nextra suits developers who already work with Next.js and React and want to build documentation sites from Markdown or MDX. It is a poor fit for non-developers or teams that want a no-code site builder. Because the README excerpt is limited to repository setup, check nextra.site for feature details before committing.

Install options & downloads