#@rspress/plugin-playground

Source Code

Provides a live editable playground for previewing components in MDX code blocks.

#Installation

npm add @rspress/plugin-playground -D

yarn add @rspress/plugin-playground -D

pnpm add @rspress/plugin-playground -D

bun add @rspress/plugin-playground -D

deno add npm:@rspress/plugin-playground -D

#Usage

#1. Register the plugin

First, write the following config in the config file:

import { 
function defineConfig(config: UserConfig): UserConfig (+1 overload)
Define a static Rspress configuration object.
@paramconfig  - The Rspress configuration object.@returnsThe  same configuration object (enables type checking and IDE autocompletion).@example
import { defineConfig } from '@rspress/core';

export default defineConfig({
  title: 'My Site',
});
defineConfig } from '@rspress/core';
import { 
function pluginPlayground(options?: Partial<PlaygroundOptions>): RspressPlugin
The plugin is used to preview component.pluginPlayground } from '@rspress/plugin-playground';

export default 
function defineConfig(config: UserConfig): UserConfig (+1 overload)
Define a static Rspress configuration object.
@paramconfig  - The Rspress configuration object.@returnsThe  same configuration object (enables type checking and IDE autocompletion).@example
import { defineConfig } from '@rspress/core';

export default defineConfig({
  title: 'My Site',
});
defineConfig({
  
UserConfig.plugins?: RspressPlugin[] | undefined
Doc pluginsplugins: [
function pluginPlayground(options?: Partial<PlaygroundOptions>): RspressPlugin
The plugin is used to preview component.pluginPlayground()],
});

#2. Use in MDX files

Use the ```tsx playground syntax in MDX files:

```tsx playground
import { useState } from 'react';

function App() {
  const [count, setCount] = useState(0);

  return (
    <div style={{ textAlign: 'center' }}>
      <p>Current count: {count}</p>
      <button onClick={() => setCount(count + 1)}>+</button>
      <button onClick={() => setCount(count - 1)}>-</button>
    </div>
  );
}

export default App;
```

It renders as follows:

#3. Write component code in other files (optional)

In addition to writing component code in the code block of the mdx file, you can also use it with File Code Block to write the example code in other files.

```tsx file="./_playgroundDemo.jsx" playground

```

It renders as follows:

#Adjusting layout direction

You can use the direction parameter to specify the layout direction of the editor and preview area. It supports horizontal or vertical.

#direction="horizontal"

Horizontal layout is the default mode, with the editor and preview area arranged side by side.

Syntax:

```tsx playground direction=horizontal

```

#direction="vertical"

Vertical layout mode, with the editor and preview area arranged top to bottom.

Syntax:

```tsx playground direction=vertical

```

Rendering result:

#Define the layout of the entire page

You can write playgroundDirection in frontmatter to define the layout of the editor and preview area for the entire page.

---
title: Title
playgroundDirection: vertical
---

Priority: Defined directly on the code block > Page frontmatter definition > Plugin configuration.

#Options

This plugin accepts a configuration object with the following type definition:

interface PlaygroundOptions {
  defaultRenderMode?: 'pure' | 'playground';
  defaultDirection?: 'horizontal' | 'vertical';
  editorPosition?: 'left' | 'right';
  babelUrl?: string;
  monacoLoader?: Parameters<typeof loader.config>[0];
  monacoOptions?: MonacoEditorProps['options'];
  include?: Array<string | [string, string]>;
  render?: string;
}

#defaultRenderMode

• Type: 'pure' | 'playground'
• Default: 'pure'

Configures the default rendering behavior for code blocks that don't explicitly declare pure or playground.

• ```tsx pure: Render as a regular code block
• ```tsx: Render based on defaultRenderMode configuration
• ```tsx playground: Render as an editable Playground component

#defaultDirection

• Type: 'horizontal' | 'vertical'
• Default: 'horizontal'

Configures the default layout direction of the editor and preview area.

#editorPosition

• Type: 'left' | 'right'
• Default: 'left'

Configures the position of the editor in horizontal layout (left/right).

#babelUrl

• Type: string
• Default: 'https://cdnjs.cloudflare.com/ajax/libs/babel-standalone/7.22.20/babel.min.js'

Playground uses @babel/standalone to compile demo code. You can modify it to a URL provided by other CDNs, such as unpkg, jsdelivr, etc.

#monacoLoader

Configures monaco-loader behaviors. Loaded from cdnjs.com by default.

You can modify it to a URL provided by other CDNs, such as unpkg, jsdelivr, etc.

The full documentation can be found at suren-atoyan/monaco-loader

#monacoOptions

• Type: IStandaloneEditorConstructionOptions

Configures Monaco Editor options.

#include

• Type: Array<string | [string, string]>

By default, this plugin will automatically scan all import statements in demos; packages not used in demos cannot be used in the Playground. If you want to add other packages to the Playground, you can use the include parameter:

pluginPlayground({
  include: [
    // Add dayjs package
    'dayjs',
    // Add a package named "my-package", actually pointing to "/path/to/package/index.js"
    ['my-package', '/path/to/package/index.js'],
  ],
});

#render

• Type: string

You can customize the render file for rendering Playground. Please note that the file name must be Playground.(jsx?|tsx?).

pluginPlayground({
  render: '/path/to/render/Playground.tsx',
});

In the custom Playground, you can directly import the original editor and renderer, and import pre-packaged dependencies through _rspress_playground_imports:

import getImport from '_rspress_playground_imports';
import { Runner, Editor } from '@rspress/plugin-playground/web';

You can refer to the built-in Playground.tsx for customization.