Docz はdoczという名前でインストールできます。またこれはテーマと一緒にインストールする必要があります。何か他に使いたいテーマがない限りdocz-theme-defaultを使います。

yarn add -D docz docz-theme-default 

Docz の設定ファイルはdoczrc.jsに書きます。とりあえず「Hello]するぐらいなら設定したほうがいい項目はtitleぐらいですね。

module.exports = {
  title: 'サイトのタイトル',
};

ページとなるファイルはプロジェクト以下の**/*.mdxファイルになります。.mdxファイルというのをあまり聞いたことがない人もいると思いますが、これはマークダウンの中で JSX を使えるようにしたもの、かつ JSX が動くのでちょっとしたスクリプトも書けるものです。地味に Prettier は既に対応済だったり最近良く使われます。

さて、.mdxファイルですがとりあえずindex.mdxとして作りましょう。 Docz の .mdxは更に頭にフロントマターを書いてそのファイル固有の設定を記述します。フロントマターというのはファイルの頭に Yaml 形式で色々定義できるやつです。

とりあえずこんな感じで作りましょう。

---
name: Foo
path: /items/foo
---

import {Playground} from 'docz';

# Foo

<Playground>
  {() => <div>Hello docz!</div>}
</Playground>

そしてyarn docz devとするとポート3000でページが開けてページが見れるはずです。

doczからインポートしているPlaygroundというコンポーネントは、その中に記述したコードをリアルタイム反映で確認できるようにしてくれたりレスポンシブ確認をしやすくしてくれる色々便利にしてくれるコンポーネントです。

Docz を TypeScript と一緒に使うのは超簡単で設定ファイルのdoczrc.jsに1行追加するだけです。このように、

module.exports = {
  title: 'サイトのタイトル',
  typescript: true,
};

typescript: trueとしましょう。

例えば./button.tsxというファイルでButtonコンポーネントを TypeScript で実装済とします。（必要なものはインストールが必要ですreactやstyled-componentsなど）であれば、.mdxファイルで単に.tsファイルのようにimportして JSX で使うだけです。

./button.tsxなのでbutton.mdxというファイルで作ります。

---
name: Button
path: /atoms/button
---

import {Playground} from 'docz';
import Button from './button';

# Button

<Playground>
  {() => <Button>Button</Button>}
</Playground>

yarn docz dev --port 4254などで起動して確認できれば完了です。

Docz も中で Webpack を使ってビルドしたりしていますが、自分のコンポーネントが自分の Webpack 設定依存の箇所を持っているとそのままだと Docz が使えなかったりします。

これには設定ファイルのdoczrc.jsでmodifyBundlerConfigという関数を設定してエクスポートします。これは第一引数に Docz の Webpack 設定を渡してくれるので、その設定オブジェクトを自分好みにした後それを返します。

例えば僕の場合webpack.DefinePluginの内容に依存しているということがありました。その時設定ファイルはこのようになりました。

const webpack = require('webpack');

module.exports = {
  title: 'サイトのタイトル',
  modifyBundlerConfig: config => {
    config.plugins.push(new webpack.DefinePlugin({
      '何かプロパティ': JSON.stringify('何か値')
    }))

    return config;
  },
};

monorepo なプロジェクトなどでたくさんのコンポーネントを1つのリポジトリで管理しているのですが、コンポーネントの数が増えていくのに伴い、開発サーバーの立ち上げ時間が明らかに遅かったり「監視ファイルの上限に…」みたいな警告を言われたり、これがストレスになってきたので、何か改善できないかと設定など読み直しました。

そこで見つけたのが--filesというオプションです。これはdoczrc.jsというような設定ファイルにも書けるのですが、オプションで都度渡すのがおすすめです。 monorepo のルートディレクトリで以下のようにコマンドを叩くことでワークスペース毎のコンポーネント開発ができるからです。（ただのglobパターンです）

# foo ワークスペースのコンポーネント開発
yarn docz dev --files 'components/foo/**/*.mdx'
# bar ワークスペースのコンポーネント開発
yarn docz dev --files 'components/bar/**/*.mdx'

# foo と bar 両ワークスペースのコンポーネント開発
yarn docz dev --files 'components/@(foo|bar)/**/*.mdx'

doczrc.js の設定が優先

少なくともdocz@0.13.7まではdoczrc.jsにfiles: '**/*.mdxと書いてしまうとコマンドの--filesオプションより優先して適用されてしまい、上書きできないので設定ファイルには記述しないでおくといいと思います。ちなみに、デフォルト値は、**/*.mdxです。

いや、ちまちま作っている。

nju33/docz-theme-figma

以下でインストールし、

yarn add -D docz-theme-figma

設定のthemeで指定すると使えます。

module.exports = {
  theme: 'docz-theme-figma',
};

最近はもう Atomic Design な考えを取り入れて Web 開発をすることがほとんどです。ただ自分の設計がまだまだ未熟なのか大抵終盤には、マイナーな要素が乱立したりしてしまいます。そしてその状態で一定期間触らないでいると、もはやそれらの存在なんか忘れてしまいます。挙げ句の果てにはその都度再定義してしまったほうが早いということで Organism 層用のファイルへ Atom 層の定義を書いてしまっていたりします。

ちなみにデザインはデザイナーさんから来たものを実装する想定ですが、何故そのようになってしまったか考えると、まずデザインの整理ができてませんでした。

例えば、トップページにあるボタン要素だけを見て実装してしまい、あとで別のページの少し違うボタンの色々を見て、うまく細分化できず様々な一部だけが違う似たような要素が乱立みたいな感じです。またその様になったあとで、急な仕様・デザイン修正が来た時にそのような要素が乱立したコードを管理していくのがどんどん難しくなっていきます。

なので、そうならないように実装前にこれから実装することになる要素について予習みたいなことをするようになり、それを Figma というツールを取り入れて行うようになりました。

Figma とはざっくり言うと

• Illustrator
• Sketch
• Affinity Defigner

みたいなツールで、四角や丸を置いたり、それらをシンボル化して使い回したり、ベジェで線を書いたりテキストを何か書いたりできるツールです。また、 XD のようなプロトタイピング機能も備えています。

Figma のいいところは誰でもすぐ見れるところです。 Web またはアプリでそのドキュメントを開けばすぐに要素の確認ができます。これはプロジェクトのディレクトリに移動して Docz やその他似たような要素管理なツールの開発サーバーを建てたあとlocalhostにアクセスして確認するというフローから入るよりかなり楽です。また環境構築の手間もいらなく、むしろ CSS を考えながら GUI でオブジェクトを弄るだけでなのでエンジニアとしても楽かと思います。

もちろん一覧できたとしてもそれはコードとしては使えませんがいいんです。ここではあくまで実装するものを洗い出しが目的です。これにより明らかにおかしい部分についても、ほぼ実装前にデザイナーさんとの間で解決した上で実装に入れるようになります。

Figma では使い回せる要素をコンポーネント化して管理できるのですが、実際に実装する要素が決まったらそこからやっと Docz などを使い要素をコード化したものを管理していきます。正直docz-theme-defaultという標準テーマでも全然大丈夫なのですが、どうせなら Figma と同じ見た目（同じサイドバーの構成）とかにクールだなと。まぁちまちま作ってる理由はそれだけです。