Install

install package

cd vitepress-project-folder

npm i vitepress-plugin-sandpack -D

TIPS: for pnpm

you also need:

pnpm add markdown-it-container -D

Problem: this package is ESM only

When importing a ESM only package by require, the following error happens.

Failed to resolve "foo". This package is ESM only but it was tried to load by require.

"foo" resolved to an ESM file. ESM file cannot be loaded by require.

ESM files cannot be loaded by require.

We recommend converting your config to ESM by either:

• adding "type": "module" to the nearest package.json

• or do follow

  renaming docs/.vitepress/config.js/docs/.vitepress/config.ts to docs/.vitepress/config.mjs/docs/.vitepress/config.mts

edit theme config, register global component

docs/.vitepress/theme/index.ts

import DefaultTheme from 'vitepress/theme';
+import { Sandbox } from 'vitepress-plugin-sandpack';
+import 'vitepress-plugin-sandpack/dist/style.css';

export default {
  ...DefaultTheme,
  enhanceApp(ctx) {
    DefaultTheme.enhanceApp(ctx);
+    ctx.app.component('Sandbox', Sandbox);
  },
}

edit config

docs/.vitepress/config.ts

import { defineConfig } from 'vitepress';
import container from 'markdown-it-container';
import { renderSandbox } from 'vitepress-plugin-sandpack';

// rule of 'html tag name' to 'component name'
// 'sanbox' -> 'Sandbox'
// 'my-sandbox' -> MySandbox
// 'sandbox-react-demo' -> SandboxReactDemo

export default defineConfig({
  // ...

  markdown: {
    config(md) {
      md
        // the second parameter is html tag name
        .use(container, 'sandbox', {
          render (tokens, idx) {
            return renderSandbox(tokens, idx, 'sandbox');
          },
        });
    },
  },

  // ...
})

then npm run docs:dev

Usage

basic usage