How to Build Nextra 3 on macOS

Building a Nextra 3 site on macOS (especially Apple Silicon) requires a few specific steps to avoid common pitfalls. Here is a comprehensive guide based on our setup.

1. Project Initialization

Create a new directory and initialize your project:

mkdir my-nextra3
cd my-nextra3
npm init -y

2. Install Dependencies

Install Next.js, React, and Nextra 3:

npm install next@^14.0.0 nextra@^3.0.0 nextra-theme-docs@^3.0.0 react react-dom

⚠️ Native Binding Fix for macOS ARM64

Nextra depends on @napi-rs/simple-git. On macOS M1/M2/M3 chips, you might encounter a “Cannot find native binding” error. Fix it by explicitly installing the Darwin ARM64 binary:

npm install --save-dev @napi-rs/simple-git-darwin-arm64

3. Configuration

next.config.js

Nextra 3 is an ESM package. If you are using a standard next.config.js (CommonJS), you need to access the default export:

const withNextra = require('nextra').default({
  theme: 'nextra-theme-docs',
  themeConfig: './theme.config.tsx',
})
 
module.exports = withNextra()

pages/_app.js (Required)

Unlike Nextra 2, Version 3 requires a custom app component to import styles. Create pages/_app.js:

import 'nextra-theme-docs/style.css'
 
export default function App({ Component, pageProps }) {
  return <Component {...pageProps} />
}

4. File Structure

Use _meta.js instead of _meta.json for better type support and flexibility.

pages/_meta.js:

export default {
  "index": "Introduction",
  "build-on-macos": "Build on macOS"
}

5. Run the Server

npm run dev

Your site should now be running at http://localhost:3000.