Gatsbyで作ったポートフォリオをv2からv3へアップデートした #React

これは何

自分のポートフォリオサイトをGatsbyで作っていて、v2からv3へアップデートした際に行ったことをまとめた記事です
- あくまで個人の事例なので詳しいアップデート手順は公式のドキュメントよりどうぞ
フロントエンド強化月間 - 開発する上で知っておくべき知見を共有しようイベントへの投稿記事でもあります

Gatsby v3とは？

ざっと特徴をまとめると以下のように変化しました。

Incremental Builds in OSS
- 必要なときだけHTMLを再生成することで、ビルドの高速化を実現
Fast Refresh
- 新しいホットリローディングエンジン、エラーリカバリー、より良いDX
gatsby-imageからgatsby-plugin-imageに
gatsby-source-wordpressがv5に
gatsby-source-contentfulがv5に

これ以外にも、プラグインの各種変更があったり、依存関係がアップデートされたりしています。
詳しくはリリースノートに載っていました。

v2からv3へ

全体の流れとしては、まずはマイグレーション用のドキュメントに従い

その後にgatsby-imageをgatsby-plugin-imageへ変更しました¹

※自分はyarnを使っているので、以下の説明は全てyarnでの内容です。npmを使っている方は適宜置き換えて読んでください。

package.jsonでのGatsbyのバージョンを上げる

$ yarn add gatsby@latest

`gatsby-`から始まるパッケージをアップデートする

yarn upgrade-interactive --latest

本体のアップデートにあわせて、関連パッケージをアップデートする必要があります。
ただし、あくまでgatsbyjs/gatsbyのリポジトリで管理されているパッケージ（＝公式のもの）だけが対象です。

Node.jsのバージョン変更

今回のアップデートで、12.13.0以上が必須になったようです。
ただし私の場合は逆に16.0.0を使っていた結果、以下のようなエラーが出てしまいました。

(node:32396) [DEP0148] DeprecationWarning: Use of deprecated folder mapping "./" in the "exports" field module resolution of the package at
/Path/To/Repository/node_modules/gatsby/node_modules/postcss/package.json.
Update this package.json to use a subpath pattern like "./*".

PostCSSの問題で、2021年4月30日現在は直っているようなのですが、Gatsbyの中で使っているバージョンがまだ古いようです。

記憶がおぼろげですが、何かを試してみたくてNode.jsのバージョンを16.0.0にしていただけだったはずなので、おとなしく推奨版である14.16.1に変えました。

変更する案内が出ているけど、自分の環境では問題なかったor使っていなかったものたち

作りとしてはかなり簡単なサイトなので、大半は変更なしで大丈夫でした。
単に列挙するだけになってしまいますが、こういったことが書いてありましたと紹介します。

Webpackを4から5へバージョンアップ
ESLintを6から7へバージョンアップ
gatsby-linkでのnavigateTo, push, replaceをnavigateに変更
__experimentalThemesを削除
pathContextをpageContextに変更
boundActionCreatorsをactionsに変更
deleteNodesの代わりにnodesのループ処理でdeleteNodeを使用
createNodeFieldでのfieldNameとfieldValueをそれぞれnameとvalueへ変更
hasNodeChangedの削除
gatsby-imageでのsizesとresolutionsをそれぞれfluidとfixedへ変更
touchNodeでnode.idではなくnodeを渡す
deleteNodeでnode.idではなくnodeを渡す
gatsby-browserAPIのうちいくつかの名前が変更
import { graphql } from "gatsby"が必須に
CSS Modulesのimportの仕方が変更に
アセットがES Modulesとしてimport可能に
GraphQLで正規表現のエスケープが変更に
GraphQLで__typenameフィールドを明示的に追加する必要がある
スキーマのカスタマイズでの変更が色々

匿名のアロー関数をなくす

チュートリアルやサンプルでは使われていますが、

export default () => {}

匿名のアロー関数だと今回の大きな変更であるFast Refreshが上手く動かない原因になるそうです。

const Named = () => {}
export default Named

これでOK。

`gatsby-image`を`gatsby-plugin-image`へ変更

今までのgatsby-imageは便利は便利だったんですがクセも強い印象でした。
それが、StaticImageコンポーネントを使うと、かなり軽減されると思います。

マイグレーションのためのドキュメントはこちらで、

gatsby-plugin-image自体の説明はこちらです。

パッケージの追加

yarn add gatsby-plugin-image gatsby-plugin-sharp gatsby-transformer-sharp

※gatsby-plugin-sharpとgatsby-transformer-sharpは普通にGatsbyを使っていればインストールしていると思いますが、一応gatsby-plugin-imageを使うのには必須なのであえて記載しています。

`gatsby-config.js`のアップデート

module.exports = {
  plugins: [
    `gatsby-plugin-image`,
    `gatsby-plugin-sharp`,
    `gatsby-transformer-sharp`,
  ],
}

コマンドを叩く

既存のgatsby-imageの書式で書かれたコードをgatsby-plugin-image用に変換するコマンドを用意してくれています。

npx gatsby-codemods gatsby-plugin-image

ただし、全部が全部このコマンドで対応できるわけでもありません。
上手く変換できなかった分はターミナル上で教えてくれるので、手動で変更します。

私の場合は今までこのようなイメージのクエリを書いていました。

query MyQuery($id: String) {
  mdx(id: { eq: $id }) {
    frontmatter {
      featuredImage {
        childImageSharp {
          fixed {
            src
          }
        }
      }
    }
  }
}

srcの取り方が変わったので、クエリを書き直し

query MyQuery($id: String) {
  mdx(id: { eq: $id }) {
    frontmatter {
      featuredImage {
        childImageSharp {
          gatsbyImageData
        }
      }
    }
  }
}

パスの渡し方を変えました。

const WorkTemplatePage = ({ data: { mdx } }) => {
- const featuredImgPath = mdx.frontmatter.featuredImage.childImageSharp.fixed.src
+ const featuredImgPath = getSrc(mdx.frontmatter.featuredImage.childImageSharp.gatsbyImageData)
  return (
    <>
      <Seo title={mdx.frontmatter.title} description={mdx.frontmatter.description} ogImagePath={featuredImgPath} />
      {/* 省略 */}
    </>
  )
}

余談ですが、gatsby-imageは読み込み中はMeduimのように粗い画像をぼかして表示するのがデフォルトだったのが、gatsby-plugin-imageではTwitterのようにベースになる1色で塗りつぶすようになっているみたいです。

gatsby-plugin-image自体はGatsbyが2.24.78以上であれば動きます。検証はできていませんが、先にgatsby-plugin-imageを導入してあとからv3へアップデートしても多分大丈夫です。 ↩

Gatsbyで作ったポートフォリオをv2からv3へアップデートした