TypeScript+Reactで始めるStorybook 7入門

StorybookはUIコンポーネントをアプリケーションから独立した状態で開発を行うためのツールです。propsを通してさまざまなバリエーションのデザインをブラウザ上に静的に表示させることがでできます。さらにブラウザ上からpropsの操作、外部リソースからのデータ取得、またテストライブラリーを利用して関数の実行、テストを行うことも可能です。またStorybookに登録したコンポーネントは自動でドキュメント化することができるのでドキュメントツールとして利用することもできます。
StorybookはReactに限らず、Vue.js, React Native, Svelte, Amber, AngularなどさまざまなJavaScriptフレームワークに対応しています。本文書ではVite上に構築したReact+TypeScript環境にStrorybookをインストールします。シンプルなコードを利用して動作確認を行なっているのでStorybookの基礎的な利用方法や機能を短時間で理解することができます。
Storybookの最新バージョンは7を利用して動作確認を行っていますがバージョン6でのReact+JavaScript環境の記事はすでに公開済みです。
環境の構築
Reactプロジェクトの作成
Viteを利用してReactのプロジェクトの作成を行います。npm create vite@latestコマンドを実行するとプロジェクト名とフレームワークの選択とvariantでTypeScriptを利用するか聞かれるのでフレークワークはReact, TypeScriptを選択してください。プロジェクト名は任意なのでここではreact-storybook7に設定しています。
作成されるプロジェクトフォルダreact-storybook7に移動してnpm installコマンドを実行します。
Storybookのインストール
npx storybook@latest initでstorybookのインストールを行います。
storybookをインストール後のpackage.jsonを確認しておきます。
npm run storybookコマンドを実行するとブラウザが自動で起動してWelcomeページが表示されます。

サンプルデータの確認
サイドメニューにあるButtonを展開するとDocs, Primay, Secondary, Large, Smallが表示されDocsをクリックするとButtonコンポーネントに関するドキュメント化された情報が表示されます。ButtonコンポーネントのデザインだけではなくPropsの情報も表示されます。

サイドメニューのDocs以外をクリックしてみましょう。Primaryだとブルーカラーのボタン、Secondaryだと白いボタン、Largeは大きなボタン、Smallだと小さなボタンというように同じボタンでも異なるデザインのボタンが表示されます。コンポーネントが持つpropsを利用して1つのコンポーネントから作成した複数のデザインをブラウザ上で確認することができます。Storybookではコンポーネントが表示されている部分をCanvasといいます。

サイドメニューに表示されているButton, Header, Pageなどはコンポーネントに対応する名前です。Buttonの下の階層にあるPrimary, Seccondary,…などをStorybookではストーリーと呼びます。1つのコンポーネントに対して複数のストーリーを設定すると各ストーリーで設定した値を元にCanvasにコンポーネントが描写されます。
フォルダ構成の確認
サイドメニューに表示されているストーリーがどのファイルに記述されているか確認するためにstorybookインストール後のフォルダ構成を確認します。プロジェクトフォルダ(react-storybook7)の中にstorybookに関係する2つのフォルダを確認することができます。1つはプロジェクトフォルダ直下に作成される.storybookフォルダ、もう一つはsrcフォルダ直下に作成されるstoriesフォルダです。
ブラウザ上に表示されている内容を記述したファイルはstoriesフォルダの中に保存されているので中身を確認するとメニューに表示されているIntroduction, Button, Header, Pageに対応するファイルを確認することができます。それらのファイルの中でファイル名に.stories.tsが含まれているファイルがStorybookのストーリーを記述しているファイルです。
初めてのStoryBook設定
サンプルとして作成されているstoriesフォルダの下にあるファイルを確認することもできますが初めてStorybookを利用する人にとって少しハードルが高いように思われるのでstoriesフォルダの中身はスキップして別のフォルダで一からストーリーを設定していきます。
Buttonコンポーネントの設定
Buttonコンポーネントを利用してStorybookの動作確認をしたいのでsrcフォルダの下にcomponentsフォルダ、componentsの下にButtonフォルダを作成しその下にButton.tsxファイルとButton.stories.tsファイルを作成します。

Button.tsxファイルに下記の内容を記述します。親コンポーネントからpropsでchildrenを受け取るだけのシンプルなコンポーネントです。
ButtonコンポーネントのストーリーをButton.stories.tsファイルに記述していきます。ストーリーといっても何か特別なものではなくButtonコンポーネントをブラウザ上でどのように描写するのかを決めるJavaScriptの関数です。ストーリーはComponent Story Format(CSF)というフォーマットを利用して記述していきます。
export defaultの中にmetadataであるtitleとcomponentを設定します。titleはサイドメニューのストーリーをまとめていたButton, Header, Pageに対応します。componentはストーリーを設定するコンポーネントを指定します。コンポーネントはimportしておく必要があります。
上記の設定の結果、exportしているmetaの型を確認すると以下のようになっています。
次にストーリーを追加します。ストーリーにHelloButtonという名前をつけてargs(argments)でButtonコンポーネントで定義したprops childernに対して”Hello World”という文字列を渡しています。定義したHelloButton関数はStroybookで利用するためにexportする必要があります。
設定は完了したのでブラウザで確認すると新たにサイドメニューに設定した”Hello Button”がCanvas上に表示されます。

ストーリーはrender関数を利用して記述することもできます。render関数の場合ファイルの中でJSXを記述するので拡張子をtsxに変更する必要があります。tsのままだとエラーになります。
render関数を利用しても先ほどと同様に”ボタン”Hello Button”が表示されます。
表示するストーリーの制御
現在の設定ではsrcフォルダ下に存在するstories.ts(tsx)ファイルが自動で検知されるように設定されているので.storybookフォルダに存在する設定ファイルmain.tsの内容を変更します。

componentsフォルダ下でstories.js/jsx/ts/tsxという名前が入ったファイルのみ自動検知できるように変更しています。
設定ファイルのmain.tsを更新した場合はStorybookを再起動する必要があるのでnpm run storybookを再実行してください。Buttonのみ表示されるようになりました。

ストーリーの追加
Button.stories.tsファイルの中のmetadataのtitleに設定したButtonはサイドメニューに表示されその中にストーリーHello Buttonが表示されます。ストーリーHello Buttonを選択すると”Hello World”のテキストが入ったボタンが表示されます。
ボタンに表示される文字を変えたい場合には同じファイル(button.stories.ts)の中に新たにストーリーを追加することでテキストの変更によってデザインにどのような違いができるのかを確認することができます。HelloButtonはrender関数、ClickButtonはargsを利用してストーリーを設定していますが表示に影響はありません。
追加後にブラウザを確認するとClickButtonのストーリーが左のサイドメニューに自動で追加され、ClickButtonを選択するとCanvas上のボタンには設定したテキストClickが表示されます。

titleの変更
titleを変更することでサイドメニューに表示される名前を変更することができますが階層化することも可能です。例えばtitleをButtonからCommon/Buttonに変更します。
Buttonの上にCOMMONが表示され階層化されることが確認できます。

titleを設定しない場合はStrobookが自動で設定を行なってくれます。metaのcomponentをコメントすると現在の設定ではHelloButtonは表示されますがClickButtonはエラーになり表示されます。ClickButtonもrender関数でButtonタグを利用することでエラーは解消します。
.storybookフォルダの確認
Storybookをインストール時に作成される.stroybookフォルダにはStrorybookの設定ファイルが保存されています。メインの設定ファイルであるmain.tsファイルを確認するとstoriesプロパティにはstoryファイルのパスが配列で設定されています。この設定によりsrcフォルダ 下の*.stories.tsx/tsが自動で認識されることを先ほど確認しました。addonsプロパティにはStorybookのアドオンが設定されておりStorybookの機能を拡張することができます。その他の設定できる項目についてはStorybookのドキュメントから確認することができます。
addonsの確認
addonsによりStorybookにどのような機能拡張が行われるのか確認していきます。
デフォルトの状態のブラウザ上に表示されるStorybookの画面を見ると上部にはさまざまなアイコンが表示されていることが確認できます。この部分をToolbarと呼びます。

main.tsファイルを開いてaddonsの中からaddon-essentialsをコメントします。
main.tsを更新した後は設定を反映させるためnpm run storybookを再実行する必要があります。
画面を確認するとToolbarに表示されていたアイコンが5つ消えていることがわかります。

addonsのessentialは複数のaddonsが含まれており公式ドキュメントから確認することができます。ドキュメントからDocs, Controls, Actions, Viewport, Backgrounds, Toolbars&globals, Measure&outlineが含まれていることがわかります。このことからToolbar上から消えたアイコンはessentialに含まれるaddonsということがわかります。
ここではそれぞれの機能がどのような動作を行うのか確認していませんがaddonsによってStorybookの機能拡張が行われていることを理解することができました。再度main.tsを元の状態に戻してaddonsのessentialsを利用できる状態にしてください。main.tsファイルの更新を行ったらnpm run storybookの再実行も忘れずに行なってください。
Autodocs
設定したStoryのコンポーネントに対してのドキュメントを自動作成してくれる機能がAutodocsです。stories.tsxファイルにtagsを追加することで自動で作成が行われます。
npm run storybookの再実行を行いブラウザを確認するとButtonの下にDocsが追加されていることがわかります。Storyも表示され一括でコンポーネントのデザインを確認することができます。

ストーリーの追加/更新
スタイルの適用
ButtonコンポーネントにCSSによるスタイルが適用できるようにButtonフォルダの中にbutton.cssファイルを作成してbutton要素に対してスタイルを適用します。
用します。
作成したbutton.cssファイルをButton.tsxファイルでimportします。
スタイルが適用されブラウザ上のボタンが変更されます。

propsの値によって背景色を変更できるように新たにpropsにcolorを追加します。デフォルト値をdefaultとします。
defaultのclassをbutton.cssに追加します。button要素の文字の色をwhiteに設定します。
デフォルトの背景色と文字が白になっていることが確認できます。

propsのcolorの値によってボタンのデザインが変わるようにbutton.stories.tsxで設定したストーリーを変更します。ストーリーの名前をDefault, Primaryに設定してPrimaryではpropsでcolorの値をprimaryとしています。
button.cssファイルにprimaryクラスを追加します。
Primaryのストーリーを選択すると背景色がブルーのボタンが表示されます。

さらに背景色の異なるストーリーDangerを追加することもできます。
CSSの追加も合わせて行います。
新たにDangerのストーリーが追加されます。

Buttonコンポーネントに設定したcolor propsに対応したストーリーを作成し、それぞれのストーリーでcolor propsに渡す値を変えることで渡した値によってどのようにボタンが表示されるかブラウザ上で確認できるようになりました。
サイズの変更
Buttonコンポーネントに背景色だけではなくサイズの変更もできるようにpropsにsizeを追加します。
size propsのdefault値はbaseとしています。baseの他にsm, lgも設定できるようにsmとlgもbutton.cssファイルに追加しておきます。文字の大きさだけではなくpaddingも変更するためbutton要素に設定していたpaddingをbase, sm, lgで設定できるように変更します。
Button.stories.tsxにカラーとサイズを指定したストーリー(PrimarySmall, PrimaryLarge)を追加します。
設定が完了するとブラウザ上から”Primary Large”と”Primary Small”が選択できるようになります。Primary Largeの場合は大きなボタン、Primary Smallの場合は小さなボタンが表示されます。Primaryの場合は通常のサイズのボタンが表示されます。

propsがある場合もrender関数を利用して記述することはできます。
Argsの再利用
argsを利用している場合は別のストーリーのargsを再利用することができます。
PrimaryとPrimarySmall, PrimaryLargeの3つのargsを比較した時children, colorは共通でsizeだけ異なる値が設定されていることがわかります。その場合はPrimarのargsを…Primary.argsとして別のストーリーで利用することができます。
Args+render関数
argsとrender関数を同時に利用することができます。その場合はrender関数の引数でargsを受け取ることができます。
Storybookが持つ機能の確認
Controls
Controlsの動作確認
StorybookのControlsを利用することでコード上ではなくUI上でargsの値を変更することができます。ControlsはAddonの一つなので@storybook/addon-essentialsの中に含まれています。
下記のようにDangerを設定したStoryをブラウザ上で確認します。
Dangerボタンの下部にControls, Actions, Interactionsのタブを確認することができます。

Controlsは非表示にすることもできるので表示されない場合はまずブラウザの右上にあるアイコンを確認します。下記の場合は左から4番目にあるアイコンがControlsのアイコンでこれが表示されている場合はブラウザ上にはControlsは表示されていません。クリックすると下部に表示されます。Controlsの表示はブラウザの右側にも表示させることも可能です。アイコンが表示されていないにも関わらず下部、右側にも表示されていない場合はブラウザのデベロッパーツールのApplicationのlocalStorageを一度クリアにしてみてください。

Buttonコンポーネントはchildren, color, sizeのpropsを持っているのでControlsにはpropsの名前とControl列が表示されています。UI上でargsの値を変更できると説明した通り、childrenのControl列のDangerをエラーに変更してみます。
UI上のボタンの文字がDangerからエラーに更新されます。argsの値をUI上で変更できることがわかりました。

DangerのStoryをrender関数を変更して表示させます。
render関数の場合はControls上でargsの値を変更することはできません。”This story is not configured to handle controls”と表示されています。

propsの型の設定
Controlsの機能を利用するためにrender関数をargsの形に戻します。
再度Controlsを確認するとchildren, color, sizeすべての値は自由な値を設定することができます。

childrenに関しては問題がありませんがcolorについてはdefault, primary, dangerのみCSSファイルに設定しています。TypeScriptでpropsの型にUnionを利用することで設定可能な値を制限することができます。Button.tsxファイルでcolorとsizeの型を更新します。
Controlsを確認するとcolor, sizeがradioボタンで選択できる値が制限されていることがわかります。


colorやsizeにButton.tsxのUnionの設定以外の値を設定するとButton.stories.tsxファイルでTypeScriptのエラーが発生します。
argTypesの設定
Button.tsxファイルのpropsの型を設定することでControlsのcolor, sizeの設定する値を制限することができました。コンポーネントファイルではなくストーリーファイルでも値の制限を行うことができます。
動作確認のためpropsの型をstringに戻します。
Button.strories.tsxではargTypesを利用してcolor, sizeの設定を行います。optionsでは設定できる値、controlのtypeでradioとselectを設定します。
typeにradioを設定するとラジオボタン、selectに設定するとselect要素として選択することができます。

Button.tsxでUnion Typeを設定してButton.stores.tsxのargTypesのoptionsを設定した場合、Storybook上ではargTypesで設定した値が表示されます。
argTypesでoptionsを設定せずcontrolのtypeのみ設定するとcontrolのtypeのみ反映されます。
Actions
clickイベントとActions
actionsの動作確認を行うためにButtonコンポーネントにonClickイベントを設定します。
ブラウザ上に表示されているボタンをクリックしてください。Controlsの横のActionsにクリックの回数とクリックイベントの情報が表示されます。

ButtonコンポーネントにonClickイベントを追加するだけでActionsが動作するようになりました。
argTypesの設定
Buttonコンポーネントではpropsで渡す名前をonClickとしていましたがhandleClickに変更します。名前をonClickからhandleClickに変更するとActionsは動作しなくなります。
handleClickでもActionsを動作させるためにButton.stories.tsxファイルのargTypesを設定します。
設定を行いボタンをクリックするとActionsにクリックのイベント情報が表示されます。argTypesのactionプロパティで設定して’clicked’は下記のようにメッセージの先頭に表示されます。

グローバル設定
なぜonClickの名前ではActionsが動作したのにhandleClickの名前ではargTypesを設定する必要があるのしょう。理由は.storybookフォルダの下にあるpreview.tsファイルで設定が行われているためです。
parametersのactionsのargTypesRegexにonから始まる名前のみActionsが動作するように設定が行われています。
parametersの設定はButton.stories.tsxファイルでも設定することができるので下記のように設定を行います。
先頭がhandleから始まる関数であればActionsが動作します。

Loadersによるデータ取得
外部サービスから非同期に取得したデータをLoadersによって利用することもできます。ここでは無料で利用できる外部サービスのJSONPladeHolderを利用します。
UserItemコンポーネントを作成します。idとnameを受け取れるようにpropsを設定を行っています。
UserItem.stories.tsxファイルを作成して以下のコードを記述します。
Storybookで確認するとUserItemがサイドバーに追加されます。

Loadersを利用してJSONPlaceHolderからデータを取得するためにfetch関数を利用します。Node.js環境でfetch関数を利用するためにはNodeのバージョンが18以上である必要があります。本環境はv18.15で動作確認しています。
FetchDataという名前でストーリーを追加しています。
Storybookで確認するとJSONPladeHolderから取得したデータが”Fetch Data”で表示されています。

loadersを利用して取得したデータをストーリーで利用できることがわかりました。
loadersの設定をmetaの中で行うこともできます。その場合はすべてのストーリーでloadersを利用することができます。
Play Functionの設定
コンポーネントに定義した関数をStorybookで描写する前に実行することができます。例えばボタンコンポーネントであればPlay Functionを利用してボタンをクリックしてユーザとのインタラクションの動作確認を行うことができます。
Play Functionを利用するためにはaddOnの@storybook/addon-interactionsをインストールする必要がありますがデフォルトでインストールが完了しています。@storybook/testing-libraryも利用しますがこちらもデフォルトでインストール済みです。追加のインストールなしで利用することができます。
Buttonコンポーネントではボタンをクリックすると実行されるhandleClickはconsole.logが実行されるようになっていますがalert関数が実行されるようにargsを設定します。
alert関数を設定するとボタンをクリックするとポップアップが表示されます。

Play Functionを追加します。play Functionのコードの中身については後ほど説明します。
追加後にDangerのストーリーを選択すると自動でポップアップが表示されます。Interationsタグに数字が1と表示され”PASS”と表示されています。動作確認(テスト)に成功したことを意味します。”Go Back”, “Go Forwad”ボタンにより何度もPlay Functionを実行することができます。

PlayFunctionの中で利用されていたcanvasElementやcanvas, buttonにはどのような情報が入っているのかconsole.logを利用して確認します。
console.logで設定した値はブラウザのデベロッパーツールのコンソールから確認します。
canvasElementはButtonコンポーネントにdiv要素がラップされている要素です。
canvasElementをwithin関数でラップすることでさまざまな関数を持つオブジェクトであることがわかります。それらの関数はコンポーネント上の要素を見つけるためのQuery関数として利用します。

canvasオブジェクトの中の関数getByRoleを利用して取得したbuttonはbutton要素であることがわかります。
useEventのclickメソッドの引数にbutton要素を設定することでクリックが行われています。
テスト
Test runner
Play Functionを追加した時にInteractionには動作確認の成功を表す”PASS”が表示されていました。複数のストーリーにPlay Functionを設定した場合に一つ一つブラウザ上で動作確認テストを行うのは効率的ではありません。Test runnerを利用することでテストを一括で行うことができます。
Test runnerではJest, PlayWrightを利用して行っています。テストはPlay Functionが記述されたstoriesだけを実行するのではなくすべてのstoriesファイルで行われます。Play Functionがない場合は各ストーリーがエラーなしで描写されるのか確認を行います。
@test-runnerのインストールを行います。
インストールが完了したらpackage.jsonファイルのscriptに実行するためにコマンドを追加します。
test-runnerを実行するための設定は完了です。package.jsonファイルに追加した後はnpm run test-storybookコマンドでTest runnerを実行することができます。
test-runnerを実行するためにはStorybookを起動しておかなければなりません。起動していない場合は下記のエラーメッセージが表示されます。
実際に実行されると以下のように表示されます。すべてのテストにPASSしたことがわかります。
verboseモード
もう少し行われたテストの内容を確認したい場合にはオプションの–verboseをpackage.jsonで追加します。
設定後再度”npm run test-storybook”を実行します。
Play Functionが含まれるButtonのDangerには”play test”と表示され残りのストーリーには”smoke-test”と表示されています。Interationsのテストが実行されたのか識別することができます。
watchAllモード
–watchAllオプションをつけることでファイルの更新を検知して自動でテストを再実行してくれます。
–watchオプションもありますが–watchを利用の場合には”–watch is not supported without git/hg, please use –watchAll”のメッセージが表示されるのでwatchAllを利用しています。
Canvas上の表示設定
Canvas上の表示設定はpreview.tsを利用したグローバルレベル、metaで設定を行うコンポーネントレベル、Story担任で設定するストーリーレベルで行うことができます。
Parametersによる背景の設定
ToolbarのアイコンをクリックすることでCanvasの背景色を変更することができます。デフォルトでは”light”と”dark”を切り替えることができます。

darkを選択すると下記のようにcanvasの背景が変わります。

その他の背景色に設定したい場合にはmetaにparametersを追加した行うことができます。
light, darkから設定したred, green, blueの選択項目が変わります。

背景色の設定はストーリー単位でも行うことができます。
Decoratorsの設定
Decoratorsを利用することでCanvasに表示されているButtonコンポーネントの外側にスタイルを設定することができます。
現在左上に表示されているButtonコンポーネントにmarginを設定したい場合には以下のようにDecoratorsを利用することで実現することができます。
Decoratorsの設定でボタンの周りにmarginが設定されています。

layoutの設定
Decoratorsを利用してスタイルを設定することで真ん中に表示させることもできますがlayoutを利用すると簡単に中央表示にすることができます。
canvasの中央に表示されます。

layoutに値にはcenteredの他にdefaultのpaddedとfullscreenがありますがpaddedとfullscreenの違いがpaddingがあるかどうかの違いです。fullscreenで画面一杯にコンポーネントが広がるわけではありません。
Viewportの設定
toolbarにあるアイコンをクリックすることでデフォルトでは”Small mobile”, ”Large mobile”, ”Table”とデフォルトの4つのviewportのサイズでコンポーネントのデザインを確認することができます。

“Small mobile”に変更するとモバイルのサイズに合わせた幅で表示されます。viewportによりレスポンシブデザインの表示確認を行うことができます。
