React 구성 요소의 편집 가능한 라이브 샘플을 위한 라이브러리인 React Runner

나는 최근에 라이브러리가 샘플 코드로 무엇을 할 수 있는지 보여주는 데모 페이지를 게시하고 싶었습니다.

실제 데모 페이지는 다음과 같습니다. 미리 설정된 샘플 코드와 React 구성 요소의 렌더링 결과가 나란히 있는 코드 편집기가 있습니다. 둘 다 다른 요소와 함께 데모 페이지에 포함되어 있습니다.


The demo page of 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

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 내 모든 요구 사항을 충족했습니다.

이것의 한 가지 단점은 샘플에서 가져올 수 있는 모든 라이브러리가 웹 페이지에 번들로 제공되어야 한다는 것입니다. 자연스럽고 기술적으로 불가피하지만 번들 크기가 더 커집니다.
아래의 Sandpack에는 이 문제가 없을 수 있습니다.

리액트 라이브

React Live

이 목적을 위한 대중적인 라이브러리. 예를 들어 Chakra UI’s doc은 아래 스크린샷과 같은 편집 가능한 예제에 이것을 사용하고 있습니다.


React Runner wrote의 저자는 React Live에서 영감을 얻었습니다. 디자인에서 React Runner는 React Live의 상위 집합처럼 보입니다.
import 문을 포함하여 완전하고 독립적인 샘플 코드를 보여주고 싶었기 때문에 React Live를 사용하지 않았지만 React Live는 이를 지원하지 않았습니다.

샌드팩

유명한 온라인 코드 편집기CodeSandbox의 구성 요소 라이브러리입니다.

내 프로젝트에서 React를 사용하고 있었기 때문에 React의 변형 @codesandbox/sandpack-react 이 후보였습니다.

이것도 좋은 라이브러리였지만 import Something from "package/subpath" 와 같은 중첩된 경로에서 가져오기를 지원하지 않기 때문에 선택할 수 없었습니다.

내 라이브러리는 ESM과 CommonJS용으로 구축되었으며 CommonJS 버전은 이러한 중첩된 가져오기를 허용하므로 이를 보여주고 싶었습니다.

이 제한이 문제가 되지 않는다면 Sandpack이 가장 좋을 수 있습니다.

빌드 시 샘플 코드 포함

일부 번들러는 일반 모듈 대신 문자열로 파일 내용을 가져올 수 있습니다. Webpack에는 raw-loader , Vite에는 ?raw query이 있습니다.

이것은 또한 각 샘플 코드를 별도의 *.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}
    />
    ...
  )
}

그러나 샘플 코드 1개당 2개의 가져오기가 필요하고 중복되었습니다. 또한 라이브 편집 경험을 제공하지 않습니다.