웹 구성 요소에 대한 스토리북 문서화를 자동화한 방법

우리는 최근updated our storybook 몇 가지 극적인 방법으로 이를 개선하는 데 사용한 프로세스를 공유하고 싶었습니다.

통신 내용을 감사하고 죽은 잎을 제거했습니다

.

누락된 항목을 추가했습니다

.

요소

를 시작하기 위해 문서를 include a simple way to supply developer shortcuts으로 수정했습니다.

고급 개발자를 위해 custom-elements.json 세부 정보를 추가했습니다

.

그렇지 않은 경우의 모습은 다음과 같습니다navigate to the vercel driven storybook.

우리가 이야기를 다루는 방법

스토리북 스토리를 자동화한 대부분의 방법은 다음과 같습니다.

동료와 사이폰이 자동으로 노브를 생성하기 위해 클래스 속성을 해제합니다!

custom-elements.json는 by our tooling을 wca 명령

과 함께 사용하여 자동 빌드web-component-analyzer package됩니다.

우리의 거의 모든 요소에는 요소 이름에 static get tag()가 있고 export 빌드하기 쉽도록 해당 클래스가 있습니다

.

맞춤형 데모 컨텐츠

를 제공하는 당사HAXSchema에 많은 요소를 연결합니다.

다음은 RPG character page이 일반적인 구현으로 어떻게 작동하는지에 대한 예입니다.

import { withKnobs } from "@open-wc/demoing-storybook";
import { StorybookUtilities } from "@lrnwebcomponents/storybook-utilities/storybook-utilities.js";
import { RpgCharacter } from "./rpg-character.js";

export default {
  title: "System|RPG Character",
  component: "rpg-character",
  decorators: [withKnobs],
  parameters: {
    options: { selectedPanel: "storybookjs/knobs/panel" },
  },
};
const utils = new StorybookUtilities();
export const RpgCharacterStory = () =>
  utils.makeUsageDocs(
    RpgCharacter,
    import.meta.url,
    utils.makeElementFromHaxDemo(RpgCharacter)
  );

동화책 유틸리티

npm install @lrnwebcomponents/storybook-utilities

NPM page

makeElementFromHaxDemo는 makeElementFromClass에서 used more broadly in any web component storybook으로 바꿀 수도 있습니다!

utils.makeElementFromClass(GitCorner,
      {
        source: 'https://github.com/elmsln/lrnwebcomponents',
        alt: "Our monorepo of all the things you see here",
        corner: true,
        size: "large"
      })

요소에 대한 클래스를 전달하는 패턴을 따릅니다(Vanilla 및 LitElement 기반이 모두 잘 작동하므로 모든 라이브러리에서 작동해야 함)

makeUsageDocs

여기에서 퀄리티가 한 단계 더 높아졌습니다. 이 기능을 통해 데모 템플릿을 전달하고 import.meta.url 다음을 포함하는 표준 문서 페이지를 구축하는 데 필요한 모든 것을 얻었습니다.

npm, yarn 또는 pnpm을 통해 설치하는 방법

프로젝트에서 사용하는 방법

custom-elements.json의 심층 API 세부 정보

github/npm 링크

custom-elements.json을 얻는 방법

따라서 이것은 아마도 그것을 처리하는 더 좋은 방법이 있을 것입니다. 그러나 저는 import.meta.url 에 상대적인 간단한 가져오기를 수행한 다음 localStorage variable 에 저장했습니다. 왜요? Storybook은 비동기 렌더링을 즐기지 않았기 때문입니다. 결과적으로 스토리를 더 많이 사용함에 따라 일종의 "표시"되는 2가지 기능이 있습니다(원격 파일에 있는 경우 유사한 방식으로 haxProperties를 가져옵니다).

특정 custom-elements.json 섹션에 대한 코드는 다음과 같습니다.

    const url = new URL(path);
    let entryFile = el.tag;
    let importPath = url.pathname.replace('/elements/','@lrnwebcomponents/').replace('.stories.js','.js');
    packageName = packageName || `${importPath.split('/')[0]}/${importPath.split('/')[1]}`;
    var description = window.localStorage.getItem(`${entryFile}-description`);
    setTimeout( async () => {
      // pull from the custom-elements json file since our tooling rebuilds this
      const d = await fetch(`${url.pathname}/../custom-elements.json`.replace('/lib/','/')).then((e) => e.json()).then(async (d) => {
        let allD = '';
        if (d.tags) {
          await d.tags.forEach((item) => {
            // ignore source versions
            if (!item.path || !item.path.startsWith('./src/')) {
              allD += item.name + "\n" + (item.path ? item.path + "\n" : '') + (item.description ? item.description + "\n" : '') + "\n";
            }
          })
        }
        return allD;
      })
      window.localStorage.setItem(`${entryFile}-description`, d);
    }, 0);

여기서 우리는 요청하는 import.meta.url 파일에서 rpg-character.stories.js를 사용하는 것을 볼 수 있습니다. 이것은 스토리를 로드한 파일의 경로를 제공하므로 custom-elements.json의 경로를 기반으로 할 수 있습니다. 우리의 도구가 동일한 디렉토리에서 실행될 때 우리는 new URL() 에서 경로 이름을 가져오고 파일 이름에서 이동하는 데 사용할 수 있는 해킹인 디렉토리( /../ )로 돌아갑니다(교체할 수 있지만 meh). 거기에서 custom-elements.json을 대상으로 지정합니다.

해당 파일을 얻은 후 json을 살펴보고 pre를 사용하여 관심 있는 내용을 인쇄합니다. wca는 태그, 설명 및 속성을 문서화하는 모든 노력을 기울였습니다. 지금 우리는 사람들이 소스를 파헤치지 않고 한눈에 보기를 원할 경우를 대비하여 인쇄하고 있습니다.

이것이 웹 구성 요소 모노 리포지토리를 자동화하는 방법에 대한 아이디어를 얻는 데 도움이 되기를 바랍니다.