長らく放ったらかしにしていた gatsby-theme-cruzoo の master ブランチを整理して v0.5.0 にアップデートしました。主目的は Gatsby の最新バージョンで使用できるようアップデートするです。元々 Gatsby v2 で作成したテーマだったので、v3 への移行には webpack 周りで良くエラーが出ました。

この記事では Gatsby v2 から v3 へ移行する際に必要なったコマンドなどを残します。Gatsby 公式のマイグレーションガイドの通り進めるとほとんど解決はできます。

Migrating from v2 to v3

関連ライブラリの一括アップデート

Gatsby をメジャーアップデートする場合は、Gatsby Plugin も全て最新にした方が良いです。yarn だと下記のコマンドでアップデートライブラリを簡単に選択できます。

yarn workspace gatsby-crudzoo upgrade-interactive --latest

space を押して 1 つずつアップデートするライブラリを選択するか、a キーを押して全部選択してから ENTER を押します。

CSS 関連

css modules が Esmodule 形式になっていてデフォルトの状態だと下記のような import ができなくなりました。

import styles from './test.module.css'

次のように import します。

import {title, content} from './test.module.css'

全てファイルで移行するのは大変だったので css Loader の設定を変更して namedExport に対応します。

css Loader の設定変更

theme 側の gatsby-config.js で gatsby-plugin-postcss のオプションを次のように変更します。これで import styles …の形が継続して使用できます。

    {
      resolve: `gatsby-plugin-postcss`,
      options: {
        cssLoaderOptions: {
          esModule: false,
          modules: {
            namedExport: false,
          },
        },
      },
    }

Webpack

develop すると webpack のエラーが出ました。theme の gatsby-node.js に path-browserify を追加して対応します。

webpack < 5 used to include polyfills for node.js core modules by default.
This is no longer the case. Verify if you need this module and configure a polyfill for it.

exports.onCreateWebpackConfig = ({ actions }) => {
  actions.setWebpackConfig({
    resolve: {
      alias: {
        path: require.resolve("path-browserify"),
      },
      fallback: {
        fs: false,
      },
    },
  });
};

css modules 使用時に import order の chuk error が出る

問題なく開発できるものの terminal にエラー文章がたくさん出て困りました。下記を参考に mini-css-extract-plugin の設定を変更して対応しました。

https://spectrum.chat/gatsby-js/general/having-issue-related-to-chunk-commons-mini-css-extract-plugin~0ee9c456-a37e-472a-a1a0-cc36f8ae6033

exports.onCreateWebpackConfig = ({ stage, actions, getConfig }) => {
  const config = getConfig();
  const miniCssExtractPlugin = config.plugins.find(
    (plugin) => plugin.constructor.name === "MiniCssExtractPlugin"
  );
  if (miniCssExtractPlugin) {
    miniCssExtractPlugin.options.ignoreOrder = true;
  }
  actions.replaceWebpackConfig(config);
};

tailwind の削除

元々 theme では tailwind を読み込んでいてスタイリングしていましたが今回から外すことにしました。理由は、theme 側で tailwind と purge css の機能を持たせると、使用する側で設定を変えにくくデバッグが面倒なことです。また、今のところ UI パーツをたくさん作るとか、多人数で使い回す想定がないので、CSS modules などで書いた方が開発早いのではと思いました。

ただ、スタイルの上書きを急ピッチで進めたものの、間に合わずスタイル未適用なパーツがたくさんできてしまいました。これらは随時スタイルを当てていく想定で、ひとまず theme は動いたら公開することにしました。

shadowing を推奨する Component の追加

theme 使用側で gatsby-config.js に色々とサイト情報を設定してもらい、それを元に　ヒーロー画面のカスタマイズをする想定でした。ただ、そうすると使用側で使いにくく、スタイリングも面倒です。なので、今回から shadowing する前提の Component をいくつか設定しています。

例えばトップページのヒーローエリアがそうです。theme では位置関係のスタイルだけ当て、shadowing しやすい小さな Component を設定しています。

import React from "react";

interface HomeHeroDescriptionProps {
  description: string;
}
export const HomeHeroDescription: React.FC<HomeHeroDescriptionProps> = (
  props
) => {
  const { description } = props;
  return <React.Fragment>{description}</React.Fragment>;
};

theme 使用側は下記の Component を作成すると独自のサイト説明を追加できます。

• src/gatsby-crudzoo/components/HomeHeroDescription.tsx

あまり shadowing が多くなるなら theme を fork して使うことが Gatsby 公式では推奨されています。ただ、そうすると theme の良いところがぐっと減ってしまうと思います。

theme 作成者が予め shadowing する Component をリストアップしておくと少し手間が省けるのではと思っています。

次の Todo はデザインのブラッシュアップ

今のデザインはシンプルな下地という感じで作成しています。実際にはもっとエレガントな感じにしたいので、少しずつデザインのブラッシュアップを進めていきたいと考えています。

ただ、自分でデザインを作るとどうしても垢抜けない感じにはなるので、そこはもうお金出してデザインしてもらうのもありかなと思っています。今年の GW も自宅生活が中心になりそうなので、集中して作ることができそうです。

そろそろ theme のバージョンを 1.0.0 にあげたいところ。