Docusaurus integration

Docusaurus is a docs-site framework (MDX pages, sidebar, search). If you write library docs with it instead of Next.js, use next-live-docusaurus to turn ```tsx live fences into editable previews. Same engine as this playground, wired through Docusaurus's CodeBlock theme.

Try it here#

These run with next-live directly (not inside Docusaurus). Edit the source and watch the preview update. That is what your readers get after you add the plugin.

Registered component: same import path Docusaurus sites use:

Preview

Source (editable)

import { Button } from '@next-live-docusaurus/modules';

export default function Demo() {
  return <Button>Hello from Docusaurus</Button>;
}

Tab inserts spaces. Press Escape and then Tab to move focus out of the editor.

Hooks + counter: no registry import needed:

Preview

Source (editable)

import { useState } from 'react';

export default function Counter() {
  const [n, setN] = useState(0);
  return (
    <button type="button" onClick={() => setN((v) => v + 1)}>
      {n}
    </button>
  );
}

Tab inserts spaces. Press Escape and then Tab to move focus out of the editor.

Playground vs Docusaurus

This page proves the snippets work. The plugin adds the live metastring, SSR-safe <BrowserOnly> fallback, title/line-number forwarding, and lazy loading so static fences never pull next-live into the server bundle.

Install#

Requires React 19 and Docusaurus 3.7+ with @docusaurus/core and @docusaurus/theme-common installed in your site.

Terminal

npm install next-live,next-live-docusaurus,prism-react-renderer

Configure the plugin#

docusaurus.config.js

import nextLivePlugin from 'next-live-docusaurus';

export default {
plugins: [
  [
    nextLivePlugin,
    { modules: './src/live-modules.ts' },
  ],
],
};

src/live-modules.ts exports components your snippets may import as @next-live-docusaurus/modules:

src/live-modules.ts

import * as React from 'react';

export const Button = ({ children }) =>
React.createElement('button', { type: 'button' }, children);

Mark a fence as live#

Add the live token to the code fence metastring:

MDX fence opener: ```tsx live

Demo.tsx

import { Button } from '@next-live-docusaurus/modules';

export default function Demo() {
  return <Button>Hello from Docusaurus</Button>;
}

Close the fence with three backticks on their own line.

Optional title and line numbers (forwarded from Docusaurus metadata):

MDX fence opener: ```tsx live title="Counter" showLineNumbers

Counter

1import { useState } from 'react';
2
3export default function Counter() {
4  const [n, setN] = useState(0);
5  return <button onClick={() => setN((v) => v + 1)}>{n}</button>;
6}

Static fences stay static#

The word live inside a quoted title must not activate live mode:

MDX fence opener: ```tsx title="a live demo"

a live demo

export default function Static() {
  return <p>Not live</p>;
}

No live token. Stays a plain static code block.

The plugin parses metastrings the same way Docusaurus's built-in live-codeblock theme does.

Run the monorepo example locally#

From the repo root (after building both packages):

tsx

npm run build -w next-live
npm run build -w next-live-docusaurus
mkdir -p examples/docusaurus/.packs
npm pack -w next-live --pack-destination examples/docusaurus/.packs
npm pack -w next-live-docusaurus --pack-destination examples/docusaurus/.packs
cd examples/docusaurus
npm ci
npm run install:packs
npm run build
npm run serve

Open http://localhost:3456 for one page with live blocks, line numbers, and static title guards.

Automated check (Playwright):

tsx

npm run test:smoke

The demo doc uses slug: /, so production output is build/index.html.