Docz 1 / 1 | nju33

とりあえず 3分で「Hello Docz」を表示できる環境を作る

関連

依存をインストール

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


  {() => Hello docz!}

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

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

TypeScript で書いたコンポーネントと一緒に使う

関連

設定ファイル

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


  {() => }

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

Webpack をカスタマイズする

関連

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

Docz の Webpack 設定を修正する

これには設定ファイルの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;
  },
};

files オプションで対象の .mdx を絞って効率よく開発する

関連

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

--files

そこで見つけたのが--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です。

Figma みたいな docz テーマを作った

関連

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

紹介

[nju33/docz-theme-figma](https://github.com/nju33/docz-theme-figma)

以下でインストールし、

yarn add -D docz-theme-figma

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

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

ちまちま作っている訳

最近はもう Atomic Design を取り入れて開発をすることがほとんどですが、まだ自分の設計が未熟なのか、進むにつれマイナーな要素が乱立してカオスになってしまいます。そしてその状態で一定期間触らないでいると、もはや忘れてしまい、その都度再定義してしまったほうが早いということで Page 層用のファイルへ Atom 層の定義を書いてしまっていたりします。

何故そのようになってしまったか考えると、デザインの整理が100％できてません。そのデザインはデザイナーさんから来た想定です。
例えば、トップページにあるボタン要素だけを見て実装してしまい、あとで別のページの少し違うボタンの色々を見て、うまく細分化できず様々な一部だけが違う似たような要素が乱立（別にこれは悪くはない）したりします。
またデザイン上ではAと定義されているが、よく見ると新しいhogeに依存のfooコンポーネントが入れ子になっていて急遽それに合わせて CSS を修正するといった具合です。これにはclass属性などを使うかもしれません。

ですがこんな感じで管理していると、さらにその後にくる急な仕様・デザイン修正が来た時に徐々に崩壊していきます。（僕の今いる会社の問題ですがまず担当プロジェクトが多いという前提がありますが、、）各プロジェクトの１コンポーネントの取りうるclass名など覚えていない。乱立した似ているコンポーネントのどこが違うのか目で見てみるまで分からない（見るから無ければ無いと判断）。みたいな具合です。

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

Figma とはざっくり言うと

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

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

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

考えがまとまったらやっと Docz などを使い要素をコード化したものを管理していきます。ここで正直docz-theme-defaultという標準テーマでも全然大丈夫なのですが、どうせなら Figma と同じ見た目（同じサイドバーの構成）とかだと受け入れてもらいやすいかなという考えに至ったので作ったという訳です。

Figma 使いましょう。