JSDoc で Storybook に共有事項を書いてみよう！
こんにちは。フロントエンドエンジニアの辻です。
今回は Storybook Docs と JSDoc による説明文の記述について触れてみます。
Storybook Docs
Storybook Docs は、コンポーネントに関連するデータを 1 つのドキュメントにまとめて閲覧する機能です。
Storybook 7 Docs の記事によると、Storybook Docs がリリースされたのが 2019 年で、今日に至るまで様々なバージョンアップがされてきたようです。
そして Storybook v7 にて抜本的な更新が入り、より使いやすくなりました。
特に便利なのが autodocs tag です。
v7 から導入されたこの機能のおかげで、Storybook Docs を簡単に自動生成できるようになりました。
例えば、以下の Button コンポーネントと、その Storybook ファイルがあるとします。
import { PropsWithChildren } from 'react'
type Button = {
type?: 'primary' | 'secondary'
}
export const Button = ({
type = 'primary',
children
}: PropsWithChildren<Button>) => {
return (
<button
className={`${
type === 'primary' ? 'bg-blue-500' : 'bg-green-500'
} text-white font-bold py-2 px-4 rounded-full`}
>
{children}
</button>
)
}import type { Meta, StoryObj } from '@storybook/react'
import { Button } from './button'
const meta = {
title: 'Button',
component: Button,
parameters: {
layout: 'centered'
},
tags: ['autodocs'], // <- 追記
argTypes: {
type: {
options: ['primary', 'secondary'],
control: { type: 'radio' }
}
}
} satisfies Meta<typeof Button>
export default meta
type Story = StoryObj<typeof meta>
export const Primary: Story = {
args: {
children: 'Primary ボタン',
type: 'primary'
}
}
export const Secondary: Story = {
args: {
children: 'Secondary ボタン',
type: 'secondary'
}
}Storybook ファイルの meta オブジェクトに tags: ['autodocs'] を追記するだけで、Storybook 上の Button に Docs ページが生成され、コンポーネントの詳細が表示されます。
すべてのコンポーネントで Storybook Docs を表示するには .storybook/main.js(main.ts) に docs: { autodocs: true } を追記します。
これで 1 ファイルごとに tags: ['autodocs'] を追記せずとも、各コンポーネントの Docs が表示されます。
module.exports = {
docs: {
autodocs: true // <- 追記
}
};Storybook Docs の説明文を JSDoc で記述する
さて、Storybook v7 ではコンポーネントの説明文を JSDoc で記述できるようになりました。
先程の Button コンポーネントの Storybook ファイルに JSDoc を追記してみます。
コメントは meta オブジェクトの上部にマークダウン記法で書いてきます。
import type { Meta, StoryObj } from '@storybook/react'
import { Button } from './button'
/**
* ## Button コンポーネント
*
* ### props
* - props.type を変更すると、ボタンの見た目が変わります。
* - props.type: primary (default) -> 青のボタンになります。
* - props.type: secondary -> 緑のボタンになります。
*/
const meta = {
title: 'Button',
component: Button,
parameters: {
layout: 'centered'
},
tags: ['autodocs'],
argTypes: {
type: {
options: ['primary', 'secondary'],
control: { type: 'radio' }
}
}
} satisfies Meta<typeof Button>
export default meta
type Story = StoryObj<typeof meta>
export const Primary: Story = {
args: {
children: 'Primary ボタン',
type: 'primary'
}
}
export const Secondary: Story = {
args: {
children: 'Secondary ボタン',
type: 'secondary'
}
}JSDoc を記述した状態で Storybook を立ち上げると、Button の Docs に説明文が表示されました。
マークダウン記法もしっかりと反映されていますね。
Storybook ファイルの JSDoc には何を書くと良さそうか
パッと思いつくものですと「デザイナーに共有する際のコメント」かなと思います。
例えば、フロントエンドエンジニアが Storybook 上にコンポーネントをまとめたうえで、デザイナーにフィードバックを求める機会があったとしましょう。
その際に「コンポーネントのココを特に確認してほしい」とか「アニメーションはこんな感じで実装しているよ」とか…を JSDoc に書いておけば、デザイナーはコンポーネントと一緒に共有事項も確認できます。
まとめ
今回は Storybook Docs と JSDoc による説明文の記述について触れてみました。
Storybook は日々進化していますので、より良い開発体験のために、今後も定期的に情報をキャッチアップしていきたいところですね。
Gaji-Labo は Next.js, React, TypeScript 開発の実績と知見があります
フロントエンド開発の専門家である私たちが御社の開発チームに入ることで、バックエンドも含めた全体の開発効率が上がります。
「既存のサイトを Next.js に移行したい」
「人手が足りず信頼できるエンジニアを探している」
「自分たちで手を付けてみたがいまいち上手くいかない」
フロントエンド開発に関わるお困りごとがあれば、まずは一度お気軽に Gaji-Labo にご相談ください。
オンラインでのヒアリングとフルリモートでのプロセス支援にも対応しています。
Next.js, React, TypeScript の相談をする！
