v3へのアップデート時に行ったエラー対処まとめ

Gatsbyとライブラリのアップデート

最初に gatsby を単体で最新にアップデートしました。

npm i gatsby@latest --legacy-peer-deps

npm v7.19.1 で作業したのですが、--legacy-peer-deps オプションをつけないと、うまくインストールできませんでした。

これで 2.32.0 だったのが、最新の 3.10.2 になりました。

次に、残りのライブラリは npm-check-updates を使って一気にupdateしました。 グローバルにインストールして実行します。

npm i -g npm-check-updates

ncu -u

これで package.json 内に記述されているバージョンが更新されたので、それに合わせて node-modules 内のパッケージを更新させます。

npm i --legacy-peer-deps

これで全てのライブラリが最新になりました。

できれば、このまま何も問題なく動いてくれれば最高なのですが、そう上手くいくわけもなく、複数のエラーの修正が必要になりました。

gatsby develop より始めよ

まずは gatsby develop して、これが動作するまで発生する問題に逐次対処していきます。

npm run develop

ERROR #11321 PLUGIN

ERROR #11321  PLUGIN

"gatsby-source-contentful" threw an error while running the setFieldsOnGraphQLNodeType lifecycle:

最初は、このエラーが複数個出ました。

これは移行ガイドでも何度も名前が出てくる gatsby-image の後継の gatsby-plugin-image をインストールすると解決しました。

npm i gatsby-plugin-image

gatsby-config.ts にもプラグインを追加します。

export const plugins = [
  `gatsby-plugin-image`
]

ちなみに有効化しただけで、内部では以前の gatsby-image を利用したままですが、このエラーは消えました。 できれば develop できない状態で内部データを触りたくなかったので、そのままエラー対処を続行しました。

【参考サイト】 reactjs - Error: Cannot find module 'gatsby-plugin-image/graphql-utils' - Stack Overflow

ERROR #98124 WEBPACK

ERROR #98124  WEBPACK

Generating development SSR bundle failed
Can't resolve '@emotion/react' in '...\work_directory\.cache'

これは使用している CSS in JS のライブラリ、emotion のエラーですね。 @emotion/react をインストールします。

npm i @emotion/react

いつの間にか @emotion/core から改名したらしいです。 新しいのじゃないとGatsby3で使えないのかな？

gatsby-plugin-image と同じくインストールしただけで、後で修正することになりますが、この時点では古い @emotion/core を利用したままです。

ERROR #98123 WEBPACK

ERROR #98123  WEBPACK

Generating development JavaScript bundle failed

Module build failed (from ./node_modules/postcss-loader/dist/cjs.js):
Error: PostCSS plugin postcss-flexbugs-fixes requires PostCSS 8.

このエラーは postcss の最新版をインストールで解決しました。

npm i postcss@latest --legacy-peer-deps

【参考サイト】 Gatsby 3 Error: PostCSS plugin postcss-flexbugs-fixes requires PostCSS 8 - gatsby

gatsby build を使って更に検証

ここまでの作業を終えると gatsby develop が実行できました。 しかし、localhost:8000 にアクセスしてサイトを表示させると真っ白で何も画面に表示されません。

とはいえ develop は最後まで実行できているのでエラーメッセージも表示されません。 なので次は gatsby build をしていきます。

develop の時と同じように、今度は build を実行して発生するエラーを潰していきます。

npm run build

ERROR #85901 GRAPHQL

ERROR #85901  GRAPHQL
There was an error in your GraphQL query:
Missing parser to attach `remark-breaks` to

gatsby-config.ts からプラグインの gatsby-remark-line-breaks を停止させるためにコメントアウトしました。

これは Markdown 内で無視されてしまう改行を br タグに変換してくれるプラグインです。 Gatsby の移行ガイドには、プラグインは対応しなくても動くとあるのですが、これは駄目なようですWoozy Face Emoji

In most cases, you won’t have to do anything to be v3 compatible.

// Google翻訳 // ほとんどの場合、v3と互換性を持たせるために何もする必要はありません。 https://www.gatsbyjs.com/docs/reference/release-notes/migrating-from-v2-to-v3/#for-plugin-maintainers

gatsby-remark-line-breaks の Git Hub を見てみると、他の方も同じエラーが出ているようで、issues は出てるけどまだ対応されてないようです。

【＊プラグインの代わりにCSSで改行することができたので別の記事にしました】

ERROR #95313

ERROR #95313 
Building static HTML failed
See our docs page for more info on this error: https://gatsby.dev/debug-html

  WebpackError: The `@emotion/core` package has been renamed to `@emotion/react`. Please import it like this `import { jsx } from '@emotion/react'`.

プロジェクト内でインポートしている @emotion/core を、先程インストールした @emotion/react に一括で置換しました。

//import { css } from '@emotion/core'
import { css } from '@emotion/react'

dvelop は完治、しかし gatsby build は未だ失敗

ここまでの作業で、gatsby develop でサイトの内容が表示されるようになりました！ しかし、まだ gatsby build は途中で失敗します。

ERROR #11321 PLUGIN

ERROR #11321  PLUGIN

"gatsby-plugin-sitemap" threw an error while running the onPostBuild lifecycle:

Body must be a string. Received: undefined.

gatsby-plugin-sitemap の options の exclude を excludes に修正。s が足りなかった。 記述は Gatsby2 の時のままなので、以前は問題なく動いてたと思うのですが、不思議。

  {
    resolve: `gatsby-plugin-sitemap`,
    // option: {
    options: {
      excludes: [`/404.html`],
    },
  },

2021-8-12追記・gatsby-plugin-sitemapはデフォルトで /404 及び 404.html を除外対象とするので、そもそも excludes を書く必要がありませんでした。

Gatsby Build の動作確認

ここで、ついに Gatsby Build も通りました。

gatsby-remark-line-breaks が Gatsby3 では動かないので、記事中の改行がなくなっていること以外は、Gatsby2 の内容と同じ内容で動作しています。

大量に出るようになったTSのエラー対策

/** @jsx jsx */
import { jsx } from '@emotion/react'

@emotion/core を @emotion/react へと置換した複数のファイルに、上記を追加。 これも Gatsby2 と @emotion/core の時は、なくてもエラー出なかったような。

Emotion - TypeScript

そして、不要になっていた @emotion/core をアンインストールしました。

npm uninstall @emotion/core

【＊上記のプラグマ追記をせずともbablel設定でエラーを消せたので別の記事にしました】

v3 未対応プラグイン問題

gatsby-remark-line-breaks 以外では、動作はしますが gatsby-plugin-next-seo がビルド時に Gatsby3 に未対応とエラーが出ます。

warn Plugin gatsby-plugin-next-seo is not compatible with your gatsby version 3.10.2 - It requires gatsby@^2

このエラーの対処だけならプラグインの peerDependencies を書き換えるだけらしいので、Gatsby3 になって以降、このプラグインは更新されてない感じでしょうか。

もし今後の Gatsby で、プラグインに対する破壊的更新があって使えなくなると困るので、できればメンテナンスを続けて欲しいところです。 当ブログはメタデータを一括してこれで扱っているのでかなり死活問題。

GitHub を確認してみると Gatsby3 への対応を望む issues が出ていますね。

おわり

とりあえず動作まではいきました。 Gatsby 公式の2から3への移行解説を見てみましたが、作成したのが Gatsby2 の後期だった当ブログでは、ここの項目に引っかかる箇所は gatsby-plugin-image しかありませんでした。

後は gatsby-imageから gatsby-plugin-image への移行が終われば完了です。