Библиотека для редактируемых живых примеров компонентов React, React Runner

Недавно я создал библиотеку компонентов React и хотел опубликовать для нее демонстрационную страницу, которая показывает, что может сделать библиотека с помощью примера кода.

На самом деле демо-страница выглядит следующим образом. Здесь есть редактор кода с заданным образцом кода и результат рендеринга React-компонента бок о бок. Оба они встроены в демонстрационную страницу вместе с другими элементами.


Демонстрационная страница react-ymd-date-select

TL;DR

Для этого React Runner оказался лучшим в моей ситуации по сравнению со следующими альтернативами.

  • React Live
    • Не поддерживает утверждения import в коде примера.
  • Sandpack (@codesandbox/sandpack-react)
    • Не поддерживает вложенные пути, такие как import Something from "package/subpath".
    • https://github.com/codesandbox/codesandbox-client/issues/6499
  • Встраивание кода примера во время сборки с помощью настроек бандлера, например, raw-loader для Webpack.
    • Это требует 2 импорта на пример, как показано ниже, но мне это не понравилось из-за избыточности.
  import SampleComponent from "./components/Sample"
  import SampleComponentCode from "./components/Sample?raw"

  ...

  <LivePreview
    component={SampleComponent}
    code={SampleComponentCode}
  />
Вход в полноэкранный режим Выход из полноэкранного режима

Требования/условия

  • Я хотел показать код примера и отрисованный компонент React бок о бок.
    • Лучше, если пользователи смогут редактировать код, а результат будет меняться динамически.
  • Эти примеры также должны использоваться в качестве тестовых наборов E2E, поэтому код каждого примера должен быть самодостаточным и исполняемым без неявных зависимостей.
    • Каждый файл компонента должен импортировать необходимые пакеты и экспортировать компонент.
  • Демо-сайт построен на React.
    • Фактическая кодовая база — https://github.com/whitphx/react-ymd-date-select/tree/main/website.
  • Целевая библиотека предназначена для React, поэтому код примеров также написан на React.
  • Они написаны на TypeScript.

Сравнение

React Runner

React Runner удовлетворил все мои потребности.

Один его недостаток заключается в том, что он требует, чтобы все библиотеки, которые могут быть импортированы в примерах, были встроены в веб-страницу. Хотя это естественно и технически неизбежно, это приводит к увеличению размера пакета.
Приведенный ниже Sandpack может не иметь этой проблемы.

React Live

React Live

Популярная библиотека для этих целей. Например, в документе Chakra UI она используется для редактируемых примеров, как на скриншоте ниже.

Автор React Runner написал, что он был вдохновлен React Live. Судя по дизайну, React Runner выглядит как суперсет React Live.

Я не использовал React Live, потому что хотел показать полный и самодостаточный код примера, включая утверждения import, но React Live этого не поддерживает.

Sandpack

Библиотека компонентов известного онлайн-редактора кода CodeSandbox.

Поскольку мой проект использовал React, его вариант для React, @codesandbox/sandpack-react, был кандидатом.

Это тоже была хорошая библиотека, но я не смог ее выбрать, потому что она не поддерживает импорт из вложенных путей, например import Something from "package/subpath".

Моя библиотека была собрана как для ESM, так и для CommonJS, и версия для CommonJS позволяла такой вложенный импорт, поэтому я хотел показать это.

Если это ограничение не является для вас проблемой, то Sandpack может быть лучшим вариантом.

Встраивание кода примера во время сборки

Некоторые бандлеры позволяют импортировать содержимое файла в виде строки вместо обычных модулей. Это raw-loader для Webpack и ?raw query для Vite.

Это также было хорошим решением, так как я мог иметь каждый пример кода в виде отдельного файла *.jsx или *.tsx, и это было удобно для написания кода.

// Sample.tsx

function SampleComponent() {
  return (
    <div>This is a sample</div>
  )
}

export default SampleComponent;
Вход в полноэкранный режим Выход из полноэкранного режима
// DemoSite.tsx

import SampleComponent from "./components/Sample"
import SampleComponentCode from "./components/Sample?raw"

...

export default function() {
  ...
  return (
    ...
    <LivePreview
      component={SampleComponent}
      code={SampleComponentCode}
    />
    ...
  )
}
Войти в полноэкранный режим Выход из полноэкранного режима

Однако, это требует 2 импорта на 1 пример кода и это было избыточно. Кроме того, он не обеспечивает возможность редактирования в реальном времени.

Оцените статью
Procodings.ru
Добавить комментарий