@rspress/plugin-preview
Исходный код

Предпросмотр компонентов из блоков кода в файлах MDX. Это полезно для документации библиотек компонентов.

Установка

npm

yarn

pnpm

bun

deno

npm add @rspress/plugin-preview -D

Использование

1. Установка плагина

Сначала добавьте следующую конфигурацию:

rspress.config.ts

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

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

2. Использование в MDX-файлах

В MDX-файлах используйте синтаксис ```tsx preview:

example.mdx

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

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

  return (
    <div style={{ textAlign: 'center' }}>
      <p>Счётчик: {count}</p>
      <button onClick={() => setCount(count + 1)}>+</button>
      <button onClick={() => setCount(count - 1)}>-</button>
    </div>
  );
}

export default App;
```

Это отображается следующим образом:

Счётчик: 0

import { useState } from 'react';

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

  return (
    <div style={{ textAlign: 'center' }}>
      <p>Счётчик: {count}</p>
      <button onClick={() => setCount(count + 1)}>+</button>
      <button onClick={() => setCount(count - 1)}>-</button>
    </div>
  );
}

export default App;

Подсказка

На данный момент работает только в файлах .mdx.
Экспортируйте компонент как default (экспорт по умолчанию), и Rspress отрендерит его автоматически.

3. Вынос кода компонента в отдельные файлы (не обязательно)

Вместо того чтобы писать код компонента прямо в блоке кода MDX, можно использовать его вместе с блоком кода из файла и хранить примеры кода в отдельных файлах.

example.mdx

```tsx file="./_demo.tsx" preview

```

_demo.tsx

import { useState } from 'react';

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

  return (
    <div style={{ textAlign: 'center' }}>
      <p>Счётчик: {count}</p>
      <button onClick={() => setCount(count + 1)}>+</button>
      <button onClick={() => setCount(count - 1)}>-</button>
    </div>
  );
}

export default App;

Это отображается следующим образом:

Счётчик: 0

import { useState } from 'react';

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

  return (
    <div style={{ textAlign: 'center' }}>
      <p>Счётчик: {count}</p>
      <button onClick={() => setCount(count + 1)}>+</button>
      <button onClick={() => setCount(count - 1)}>-</button>
    </div>
  );
}

export default App;

Использование режима предпросмотра iframe

Этот плагин поддерживает несколько режимов предпросмотра. Переключаться между ними можно, изменяя мета-информацию preview="...". Например, ```tsx preview="iframe-follow" переключает в режим iframe-follow.

```tsx preview эквивалентно ```tsx preview="{defaultPreviewMode}", значение определяется параметром defaultPreviewMode.

Подсказка

Режим предпросмотра iframe имеет отдельные среды компиляции и выполнения.

Отдельное окружение сборки: пример кода в блоке кода компилируется как точка входа отдельным экземпляром Rsbuild, что позволяет внедрять переменные Sass/Less и другую конфигурацию.
Отдельное окружение выполнения: исключаются конфликты стилей с сайтом документации, а библиотека компонентов может загружать собственный base.css.

`preview="internal"`

"internal" — режим предпросмотра по умолчанию, при котором компонент рендерится непосредственно внутри документа.

Синтаксис:

example.mdx

```tsx file="./_demo.tsx" preview

```

или

example.mdx

```tsx file="./_demo.tsx" preview="internal"

```

Отобразится так:

Счётчик: 0

import { useState } from 'react';

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

  return (
    <div style={{ textAlign: 'center' }}>
      <p>Счётчик: {count}</p>
      <button onClick={() => setCount(count + 1)}>+</button>
      <button onClick={() => setCount(count - 1)}>-</button>
    </div>
  );
}

export default App;

`preview="iframe-follow"`

Этот режим отображает область предпросмотра iframe справа от блока кода, следуя потоку содержимого.

Синтаксис:

example.mdx

```tsx file="./_demo.tsx" preview="iframe-follow"

```

Отобразится так:

import { useState } from 'react';

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

  return (
    <div style={{ textAlign: 'center' }}>
      <p>Счётчик: {count}</p>
      <button onClick={() => setCount(count + 1)}>+</button>
      <button onClick={() => setCount(count - 1)}>-</button>
    </div>
  );
}

export default App;

`preview="iframe-fixed"`

Этот режим отображает фиксированную область предпросмотра iframe справа на странице, идеально подходит для документации мобильных библиотек компонентов.

Синтаксис:

example.mdx

```tsx file="./_demo.tsx" preview="iframe-fixed"

```

Отобразится так:

Советы по preEntry

Вы можете внедрить глобальные скрипты или стили в окружение предварительного просмотра iframe, используя iframeOptions.builderConfig.source.preEntry. Вот несколько распространённых случаев использования:

Эмуляция сенсорных событий для мобильных устройств: Эмулируйте мобильные сенсорные события на ПК, импортировав @vant/touch-emulator.
Обработка тёмного режима: Внедрите MutationObserver для отслеживания изменений класса html.dark, затем синхронизируйте с body.dark или выполните другую обработку тёмного режима.
Использование Tailwind CSS: Поскольку среда предпросмотра в iframe — это отдельный экземпляр Rsbuild, если ваши компоненты, отображаемые в предпросмотре, зависят от Tailwind CSS v4, настройте @rsbuild/plugin-tailwindcss в iframeOptions.builderConfig.plugins и внедрите вашу точку входа Tailwind CSS через preEntry.

rspress.config.ts

import { pluginTailwindcss } from '@rsbuild/plugin-tailwindcss';

pluginPreview({
  iframeOptions: {
    builderConfig: {
      plugins: [pluginTailwindcss()],
      source: {
        preEntry: [
          '@vant/touch-emulator',
          './src/dark-mode-observer.js',
          './tailwind.css',
        ],
      },
    },
  },
});

Опции

Этот плагин принимает объект конфигурации со следующей типизацией:

interface PreviewOptions {
  defaultRenderMode?: 'pure' | 'preview';
  defaultPreviewMode?: 'internal' | 'iframe-fixed' | 'iframe-follow';
  iframeOptions?: IframeOptions;
  previewLanguages?: string[];
  previewCodeTransform?: (codeInfo: {
    language: string;
    code: string;
  }) => string;
}

interface IframeOptions {
  devPort?: number;
  builderConfig?: RsbuildConfig;
  customEntry?: (meta: CustomEntry) => string;;
}

defaultRenderMode

Тип: 'pure' | 'preview'
По умолчанию: 'pure'

Определяет поведение по умолчанию для блоков кода, в которых явно не указаны pure или preview.

Предупреждение

Не рекомендуется изменять значение по умолчанию, поскольку это может повлиять на совместное использование с @rspress/plugin-playground.

```tsx pure — рендерится как обычный блок кода
```tsx — рендерится согласно настройке defaultRenderMode
```tsx preview — рендерится как блок кода с предпросмотром компонента

defaultPreviewMode

Тип: 'internal' | 'iframe-follow' | 'iframe-fixed'
По умолчанию: 'internal'

Определяет [режим предпросмотра]](#preview-mode) по умолчанию для ```tsx preview.

```tsx preview — использует режим, заданный в defaultPreviewMode
```tsx preview="internal" — режим internal
```tsx preview="iframe-follow" — режим iframe-follow
```tsx preview="iframe-fixed" — режим iframe-fixed

iframeOptions

Для режимов iframe плагин запускает отдельный экземпляр Rsbuild (как для dev-сервера, так и для сборки), полностью изолированный от процесса компиляции документации Rspress.

iframeOptions.devPort

Тип: number
По умолчанию: 7890

Настраивает порт dev-сервера для предпросмотра в iframe. Если указанный порт уже занят, плагин автоматически попробует следующий порт, до 20 попыток.

iframeOptions.builderConfig

Настраивает параметры сборки Rsbuild для iframe, например, добавление глобальных стилей или скриптов.

Например, чтобы добавить поддержку Less или Sass в превью, установите и настройте соответствующий плагин Rsbuild:

npm

yarn

pnpm

bun

deno

npm add @rsbuild/plugin-less -D

rspress.config.ts

import { defineConfig } from '@rspress/core';
import { pluginPreview } from '@rspress/plugin-preview';
import { pluginLess } from '@rsbuild/plugin-less';

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

iframeOptions.customEntry

Позволяет задать пользовательскую точку входа для поддержки других фреймворков, например Vue.

Внимание

Доступно только в режиме preview="iframe-follow".

Пример для фреймворка Vue:

import { defineConfig } from '@rspress/core';
import { pluginPreview } from '@rspress/plugin-preview';
import { pluginVue } from '@rsbuild/plugin-vue';

export default defineConfig({
  // ...
  plugins: [
    pluginPreview({
      previewMode: 'iframe',
      previewLanguages: ['vue'],
      iframeOptions: {
        position: 'follow',
        customEntry: ({ demoPath }) => {
          return `
          import { createApp } from 'vue';
          import App from ${JSON.stringify(demoPath)};
          createApp(App).mount('#root');
          `;
        },
        builderConfig: {
          plugins: [pluginVue()],
        },
      },
    }),
  ],
});

previewLanguages

Тип: string[]
По умолчанию: ['jsx', 'tsx']

Определяет языки кода, для которых включён предпросмотр. Чтобы добавить поддержку других форматов (например, JSON или YAML), используйте эту опцию вместе с previewCodeTransform.

previewCodeTransform

Тип: (codeInfo: { language: string; code: string }) => string
По умолчанию: ({ code }) => code

Выполняет пользовательское преобразование кода перед предпросмотром.

В примере ниже показано, как превратить JSON Schema в рендерящийся React-компонент:

{
  "type": "div",
  "children": "Рендеринг JSON"
}

Настроить можно следующим образом:

pluginPreview({
  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;
    }
  },
});

Миграция с V1

При переходе с Rspress V1 функциональность плагина остаётся прежней. Изменился только синтаксис исходного кода MDX:

<code src="./foo.tsx"/> → нужно заменить на Блок кода из файла: tsx file="./foo.tsx"
Опция defaultPreviewMode заменяет прежние iframeOptions.position и previewMode
Значение по умолчанию defaultRenderMode изменилось с 'preview' на 'pure'
@rsbuild/plugin-less и @rsbuild/plugin-sass больше не встроены. Если вам нужна поддержка Less или Sass в превью, установите соответствующий плагин и настройте его через iframeOptions.builderConfig:

npm

yarn

pnpm

bun

deno

npm add @rsbuild/plugin-less -D

rspress.config.ts

import { defineConfig } from '@rspress/core';
import { pluginPreview } from '@rspress/plugin-preview';
import { pluginLess } from '@rsbuild/plugin-less';

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

Примеры миграции

Пример 1:

Раньше: требовалось объявлять и в конфиге, и в MDX-файле.

pluginPreview({
  previewMode: 'iframe',
  iframeOptions: { position: 'fixed' },
});

```tsx preview

```

После: достаточно объявить только в MDX-файле.

```tsx preview="iframe-fixed"

```

Пример 2:

Раньше: использовался атрибут iframe или previewMode="iframe".

```tsx iframe

```

{/* or */}

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

После: используется единый атрибут preview="...".

```tsx preview="iframe-follow"

```

```tsx file="./_demo.tsx" preview="iframe-follow"

```

#@rspress/plugin-preview Исходный код

#Установка

#Использование

#1. Установка плагина

#2. Использование в MDX-файлах

#3. Вынос кода компонента в отдельные файлы (не обязательно)

#Использование режима предпросмотра iframe

#preview="internal"

#preview="iframe-follow"

#preview="iframe-fixed"

#Опции

#defaultRenderMode

#defaultPreviewMode

#iframeOptions

#iframeOptions.devPort

#iframeOptions.builderConfig

#iframeOptions.customEntry

#previewLanguages

#previewCodeTransform

#Миграция с V1

@rspress/plugin-preview
Исходный код

Установка

Использование

1. Установка плагина

2. Использование в MDX-файлах

3. Вынос кода компонента в отдельные файлы (не обязательно)

Использование режима предпросмотра iframe

`preview="internal"`

`preview="iframe-follow"`

`preview="iframe-fixed"`

Опции

defaultRenderMode

defaultPreviewMode

iframeOptions

iframeOptions.devPort

iframeOptions.builderConfig

iframeOptions.customEntry

previewLanguages

previewCodeTransform

Миграция с V1