@rspress/plugin-preview#

Used to preview components in the code block of md(x) files.

Installation#

npm add @rspress/plugin-preview -D

Usage#

Register#

First, write the following config in the config file:

import { defineConfig } from 'rspress/config';
import { pluginPreview } from '@rspress/plugin-preview';

export default defineConfig({
  plugins: [pluginPreview()],
});

Internal Components#

The component code of internal components is declared in the mdx file. You can declare the following code block in the mdx file:

```tsx
function App() {
  return Hello World;
}

export default App;
```

It's worth noting that you need to export the component as default, and Rspress will automatically render this component.

But if you want to keep the style of the code block instead of rendering it as a component, you can add the pure identifier to specify, the usage is as follows:

```tsx pure
function App() {
  return Hello World;
}
export default App;
```

If you have set defaultRenderMode to 'pure', Rspress will not render this component by default, but instead display it as a code block. If you want to render a code block as a component in this situation, you can do add the preview identifier to specify, the usage is as follows:

```tsx preview
function App() {
  return Hello World;
}
export default App;
```

External Components#

In addition to writing the component code in the code block of the mdx file, you can also write the component code in an external file, and then import it in the mdx file through the code tag. For example

<code src="./Demo.tsx" />

export default function App() {
  return <div>Hello World</div>;
}

External components also need to export the component as default. Through the src attribute of the code tag, you can specify the path of the external component. This plugin supports both relative paths and alias paths(alias).

For some more complex components, this way of using external components will be more convenient.

Options#

This plugin accepts an object parameter of the following type:

interface PreviewOptions {
  previewMode?: 'internal' | 'iframe';
  iframeOptions?: IframeOptions;
  defaultRenderMode?: 'pure' | 'preview';
}

interface IframeOptions {
  framework?: 'react' | 'solid';
  position?: 'fixed' | 'follow';
  devPort?: number;
}

defaultRenderMode#

The default mode of rendering internal code blocks that do not have the pure or preview identifiers declared by users, defaulting to preview.

• pure: render as regular code block
• preview: render as component

previewMode#

The previewMode parameter is used to specify whether the preview mode is internal, defaulting to internal. The default mode display effect is as follows:

You can also set it for each individual code block:

<code src="./Demo.tsx" previewMode="iframe"/>

```tsx iframe
function App() {
  return Hello World;
}
export default App;
```

If previewMode is inframe, you can use the following configuration for the iframe:

iframeOptions.position#

In iframe preview mode, you can use the iframeOptions.position parameter to determine the position of the preview area iframe, whether it follows page scrolling (follow mode) or is fixed on the page (fixed mode), defaulting to follow.

The effect of follow mode is as follows:

The effect of fixed mode is as follows:

iframeOptions.framework#

In iframe preview mode, you can choose the rendering framework, currently supports react and solid.

iframeOptions.devPort#

In the iframe preview mode, you can configure the dev server port of the preview component.

iframeOptions.builderConfig#

Configure the buildConfig of the iframe, such as adding some global code.

deprecated: isMobile#

From v1.12.0, please use previewMode instead.

deprecated: iframePosition#

From v1.12.0, please use iframeOptions.position instead.

previewLanguages#

• Type: string[]
• Default: ['jsx', 'tsx']

The code languages that support preview, by default jsx and tsx codes are supported. If you need to support other formats of code, such as json/yaml, you can use it in conjunction with the previewCodeTransform configuration below.

previewCodeTransform#

• Type: (codeInfo: { language: string; code: string }) => string
• default: ({ code }) => code

Customize the transformation of the code before previewing. For example, if you want to render a piece of JSON Schema through custom transformation logic:

{
  "type": "div",
  "children": "Render from JSON"
}

You can make the following configuration:

pluginPreview({
  // Note to add the default jsx and tsx
  previewLanguages: ['jsx', 'tsx', 'json'],
  previewCodeTransform(codeInfo) {
    if (codeInfo.language === 'json') {
      return `
import React from 'react';

const json = ${codeInfo.code};

export default function() {
return React.createElement(json.type, null, json.children);
}
`;
    } else {
      return codeInfo.code;
    }
  },
});

In this way, the component code after custom logic transformation will be rendered in the end.