@docusaurus/core vs nextra: Architecture, DX, and Customization

Both @docusaurus/core and nextra are designed to help developers build fast, content-focused websites using React and MDX. However, they approach the problem from different angles — Docusaurus is a dedicated documentation engine, while Nextra is a Next.js extension. Let's compare how they handle real-world engineering challenges.

🏗️ Core Architecture: Dedicated SSG vs Next.js Extension

@docusaurus/core is a standalone Static Site Generator (SSG).

• It manages its own build process, routing, and server rendering.
• You do not need to know Next.js to use it effectively.

// docusaurus: Standalone build command
// package.json
{
  "scripts": {
    "start": "docusaurus start",
    "build": "docusaurus build"
  }
}

nextra runs on top of Next.js.

• It inherits Next.js features like API routes, Image Optimization, and middleware.
• Your docs site is technically a Next.js application.

// nextra: Next.js build command
// package.json
{
  "scripts": {
    "dev": "next dev",
    "build": "next build"
  }
}

⚙️ Configuration: Centralized vs Distributed

@docusaurus/core uses a single config file for most settings.

• docusaurus.config.js holds theme, plugins, and navbar settings.
• Easier to audit but can become large for complex projects.

// docusaurus: docusaurus.config.js
module.exports = {
  title: 'My Docs',
  themeConfig: {
    navbar: { title: 'Home' }
  },
  presets: [['@docusaurus/preset-classic', {}]]
};

nextra splits config between Next.js and theme files.

• next.config.js handles build settings.
• theme.config.tsx handles UI and navigation.

// nextra: next.config.js
const withNextra = require('nextra')({
  theme: 'nextra-theme-docs',
  themeConfig: './theme.config.tsx'
});

module.exports = withNextra();

🎨 Theming: Swizzling vs Component Override

@docusaurus/core uses a "swizzle" system for theming.

• You copy internal components to your local src folder to edit them.
• Provides stability but can break on major version upgrades.

// docusaurus: Swizzle a component
npx docusaurus swizzle @docusaurus/theme-classic Navbar

// docusaurus: Modified src/theme/Navbar.js
export default function Navbar(props) {
  // Custom logic here
  return <OriginalNavbar {...props} />;
}

nextra uses standard Next.js component shadowing.

• You create a theme.config.tsx to override layout parts.
• Feels more like standard React development.

// nextra: theme.config.tsx
export default {
  logo: <span>My Project</span>,
  project: { link: 'https://github.com/...' },
  useNextSeoProps() {
    return { titleTemplate: '%s – My Project' }
  }
}

📚 Content Features: Versioning vs Flexibility

@docusaurus/core has built-in documentation versioning.

• You can snapshot docs for v1, v2, etc., automatically.
• Critical for libraries with breaking changes.

// docusaurus: Create a new version
npx docusaurus docs:version 2.0

// Creates versioned_docs/version-2.0/ folder automatically

nextra relies on file structure for organization.

• No built-in versioning command; you manage folders manually.
• Gives you full control but requires more setup.

// nextra: Manual versioning structure
/docs
  /v1
    /getting-started.mdx
  /v2
    /getting-started.mdx

🌐 Internationalization (i18n)

@docusaurus/core supports i18n out of the box.

• Configure locales in docusaurus.config.js.
• Automatically generates localized routes and builds.

// docusaurus: i18n config
i18n: {
  defaultLocale: 'en',
  locales: ['en', 'fr'],
  localeConfigs: { en: { label: 'English' } }
}

nextra supports i18n via Next.js routing.

• You configure it in next.config.js using Next.js i18n support.
• Requires manual setup for locale switching UI.

// nextra: Next.js i18n config
module.exports = {
  i18n: {
    locales: ['en', 'fr'],
    defaultLocale: 'en'
  }
}

🤝 Similarities: Shared Ground Between Docusaurus and Nextra

While the architectures differ, both tools share core goals and capabilities.

1. 📝 MDX Support

• Both allow you to write Markdown with embedded JSX components.
• Enables interactive documentation (e.g., live code editors).

// Both: MDX usage
import { MyComponent } from '../components';

# Hello World
<MyComponent prop="value" />

2. 🔍 Search Functionality

• Both offer built-in or easy-to-integrate search solutions.
• Docusaurus uses Algolia DocSearch; Nextra supports Pagefind/Algolia.

// Docusaurus: Algolia config
themeConfig: {
  algolia: { appId: '...', apiKey: '...' }
}

// Nextra: Search component
import { Search } from 'nextra-theme-docs';
<Search />

3. 🚀 Performance

• Both generate static HTML for fast initial loads.
• Support code splitting and lazy loading by default.

// Both: Automatic code splitting
// No extra config needed for basic optimization

4. 📱 Responsive Design

• Both themes are mobile-friendly out of the box.
• Include hamburger menus and collapsible sidebars.

/* Both: Mobile styles handled by theme */
/* No custom media queries needed for basic layout */

📊 Summary: Key Similarities

🆚 Summary: Key Differences

💡 The Big Picture

@docusaurus/core is like a specialized construction kit 🏗️ — it comes with all the tools specifically for documentation (versioning, i18n, blogs) pre-installed. It is the safer choice for large-scale public documentation where long-term maintenance and standard features are critical.

nextra is like a modular extension pack 🔌 — it turns your existing Next.js app into a docs site. It is the better choice for teams already invested in the Next.js ecosystem who need to blend documentation with custom application logic or design requirements.

Final Thought: If you are starting a pure documentation project from scratch, Docusaurus reduces risk. If you are adding docs to an existing Next.js product, Nextra reduces friction.