共通コンポーネントの説明書をStorybookで作ってみた【Angular】

はじめに

「共通コンポーネントをみんなに使ってもらう時、いちいち使い方を説明するのはしんどそう」
という事で、Storybookというコンポーネントカタログを使い、サンプルと説明を合わせて見せられる状態を作ってみました。

こんな感じです。

これを ↓ の流れで作ってみたので書いていきます。

1. Librayの作成
2. Storybookの導入
3. storyを追加
4. addon-docsを使って見せ方を変える

---

Libraryの作成

今回は共通コンポーネントの配布を予定していた為、Libraryを作りました。
「そんなの知ってる」 or 「配布しない」といった方は読み飛ばしてください。

1. ライブラリを作成します

   ng g library shared
   

2. コンポーネントを作成します

   ng g component Hogehoge --project shared
   

3. コンポーネントの中身を実装します

4. 作ったコンポーネントを使えるよう、エクスポートします
   shared.module.ts

   @NgModule({
       exports: [SharedComponent,HogehogeComponent]
   })
   

5. ライブラリをビルドします

   ng build --project=shared
   

これでdist/sharedが作られたと思います。これを配布して使ってもらいます。

---

Storybookの導入

ライブラリの説明書を作っていきます。
導入方法はここの通りです。

1. 自動セットアップをします

   npx -p @storybook/cli sb init --type angular
   

2. Storybookを起動します

   yarn storybook
   

こんな感じになれば成功です

---

storyを追加する

色々書き方があるらしい...今回は CSF という書き方で書いていきます。

1. storiesフォルダにhogehoge.stories.tsを作成します。

2. Hogehoge.stories.tsにstoryを追加する為に、

   export default -> このstory全体の設定

   export const hogehoge -> 追加するstory
   を書いていきます。
   shared.module.ts

   import { moduleMetadata } from '@storybook/angular';
   import { SharedModule } from '../../projects/shared/src/lib/shared.module';
   import HogehogeNote from './HogehogeNote.md';
   
   export default {
       title: 'HogehogeComponent',
       parameters: {
           notes: { markdown: HogehogeNote }
       },
       decorators: [
           moduleMetadata({
               imports: [SharedModule],
           }),
       ],
   };
   
   export const story = () => ({
       template: `
       <lib-hogehoge [buttonStyle]="'blue'" [name]="'Hoge'"></lib-hogehoge>
       `
   });
   

   【補足】

   • title:はこのstory全体のタイトル。
   • notes:はコンポーネントの補足情報。手順3にて作成する.mdを読み込ませています。なくてもよい。
   • moduleMetadata({imports:[]})はコンポーネントを動かす際に必要なモジュール等を記載しています。
   • template:はCanvasに表示するコンポーネントを記載しています。

3. hogehogeNote.mdファイルを作成し、Noteに表示する内容を記載します

4. storybookを起動します

   yarn storybook
   

こんな感じになります。
ここではあらかじめ作っていたHogehogeComponentが表示されています。
Canvasタブ

Notesタブ

---

addon-docsを使って見せ方を変える

addon-docsというアドオンを使っていきます。

1. 下記コマンドでインストールします

   yarn add -D @storybook/addon-docs
   

2. .storybook配下にpresets.jsを作成して以下のコードを追加します

   module.exports = ['@storybook/addon-docs/angular/preset'];
   

3. 下記のコマンドでstorybookを起動します

   yarn storybook --docs
   

   こんな感じになります
   

4. 表示のされ方に合わせてmarkdownやstoryを追加・修正します
   今回は、以下のような修正をしました。

   • HogehogeNote.mdに記載していた文言の一部をcomponentSubtitleに移動
   • storyを追加し、作ったコンポーネントの使用例を並べる

   Hogehoge.stories.ts

   export default {
    ~省略~
    parameters: {
      componentSubtitle: 'Hogehogeのガイド',
      notes: { markdown: HogehogeNote }
    },
    ~省略~
   };
   
   export const story = () => ({
      ~省略~
   });
   
   export const example = () => ({
      template: `
      <lib-hogehoge [buttonStyle]="'blue'" [name]="'blue'"></lib-hogehoge>
      <lib-hogehoge [buttonStyle]="'blue-border'" [name]="'blue-border'"></lib-hogehoge>
      <lib-hogehoge [buttonStyle]="'yellow'" [name]="'yellow'"></lib-hogehoge>
      <lib-hogehoge [buttonStyle]="'yellow-border'" [name]="'yellow-border'"></lib-hogehoge>
      <lib-hogehoge [buttonStyle]="''" [name]="'none'"></lib-hogehoge>
      `
   });
   

できましたーー！お疲れ様です。

ちなみにビルドは下記コマンドです。

yarn build-storybook --docs

---

addon-docs以外にも様々なaddonが公開されており、色々な見せ方・使い方がありそうです。
素敵な使い方があったら教えてください。