もくじ

Gatsby.jsをv2からv3へアップデート。

ハウツー
コロのicon
コロ

Gatsby3系は3つの大きなアップデートがありました。

1. 開発時のbuildスピードを80%改善

時間がかかっていた開発環境ビルド速度が大幅に改善されました。
規模が大きいサイト、media-richサイトでも待ち時間なく開発できるようになったようです。

2. Incremental Buildsによってビルド時間を高速化

Incremental Builds was initially only available in Gatsby Cloud.
Gatsby open-source now has Incremental Builds enabled by default, anywhere you decide to run your project!
This dropped build times for sites from multiple minutes to under 10 seconds in many cases.
Gatsby Cloud上でしか使うことができなかったIncremental Buildsが可能になり、数分かかっていたビルド時間が10秒以下にまでなっています。

3. 画像最適化を行うGatsby Imageの大幅アップデート

core web vitals and higher Lighthouse scores
画像最適化プラグインを大幅にアップデートすることで、サイトパフォーマンスが以前より高くなりました。

V3にするときにやったこと

公式ドキュメントを参考にv2からv3にアップデートしました。

Node.jsのバージョン確認

12.13.0以上が推奨されています。
Minimal Node.js version 12.13.0

install Gatsby.js v3

npm install gatsby@latest

関連パッケージのアップデートが必要か確認

gatsby-*のパッケージは全てアップデート対象です。
ただしコミュニティプラグインを使用している場合は個別で対応が必要です。 
$ npm outdated
対応が必要なパッケージ一覧が表示される
Package                                Current   Wanted  Latest  Location
babel-plugin-styled-components         MISSING   1.12.0  1.12.0  gatsby-starter-hello-world
gatsby-image                           MISSING   2.11.0   3.8.0  gatsby-starter-hello-world
gatsby-plugin-breadcrumb               MISSING   11.0.0  12.1.1  gatsby-starter-hello-world
gatsby-plugin-catch-links              MISSING   2.10.0   3.8.0  gatsby-starter-hello-world

outdatedで対象になったプラグインをアップデート

npm install gatsby-***@latest
もう一度 npm outdatedで確認。
何も表示されなければ次のステップへ。

ビルドしてみる

修正が必要な箇所(コミュニティプラグイン、旧gatsby-imageの使用)などがあれば警告・エラーが表示されます。
$ gatsby build

修正が必要だった箇所

サイトマップ生成プラグイン(gatsby-plugin-sitemap)
非推奨のコミュニティプラグイン(複数)
画像最適化プラグインの使用(gatsby-image)
sitemap.xmlを生成してくれるプラグインの仕様が変わっていたので、gatsby-configの内容を修正しました。
# エラー内容
"gatsby-plugin-sitemap" threw an error while running the onPostBuild lifecycle:

フォルダパス指定しかできなくなった。

output: `/hogehoge` で指定フォルダ内に sitemap-index.xml と sitemap-0.xml が生成される。
なにも指定しないと /sitemap フォルダ内に生成される。
sitemap.xmlを生成したい場合は、gatsby-plugin-sitempを3系に戻す必要がある。
💡
サーチコンソールでsitemapを送信している場合は、 sitemap-index.xmlに変更する。

excludeをexcludes に変更

除外するpathを指定するオプション名が変更されています。
gatsby-config.js
{
  resolve: `gatsby-plugin-sitemap`,
  options: {
    - output: `/sitemap.xml`, 
    - exclude: [`/aaa`],
		+ excludes: [`/aaa`],

  },
},

コミュニティプラグインのエラー

オフィシャルプラグインの他にコミュニティプラグインも使用していたので、そちらのエラーも対応しました。
warn Plugin gatsby-plugin-next-seo is not compatible with your gatsby version 3.8.0 - It requires gatsby@^2
warn Plugin gatsby-remark-fenced-divs is not compatible with your gatsby version 3.8.0 - It requires gatsby@^2.0.0

v3に対応していなかったコミュニティプラグイン

DEPRECATED(非推奨)になっていた。
マークダウンにclassを指定できる便利なプラグインでしたが使用をやめました。
gatsby-plugin-next-seoで、リッチスニペットを簡単に生成できる BreadcrumbJsonLd をつかっていた。
書き換え可能な範囲だったのでreact-helmetにプラグインを変更して対応しました。

react-helmetでJSON-LDを埋め込む

itemListElementの中身は別で自動生成しました。
import Helmet from 'react-helmet'

const jsonLd = {
  "@context": "https://schema.org",
  "@type": "BreadcrumbList",
  "name": "パンくずリスト",
  "itemListElement": [
		{
	    "@type": "ListItem",
	    "position": 1,
	    "item": {
	      "@id": 'https://your-domain',
	      "name": 'Home',
	      "@type": "Thing"
	    }
		}
	]
}

return (
	<Helmet 
		script={[
			{
				type: 'application/ld+json',
			  innerHTML: JSON.stringify(jsonLd)
			}
		]}
	/>
)
確認の為リッチリザルトテストを行う。
An image from Notion

画像最適化プラグイン変更

従来の gatsby-image から gatsby-plugin-image への変更を行いました。
ビルドで表示されたメッセージにのっていた公式のマイグレート方法を参考にすすめました。
[gatsby-transformer-sharp] The "fixed" and "fluid" resolvers are now deprecated. 
Switch to "gatsby-plugin-image" for better performance and a simpler API. 
See https://gatsby.dev/migrate-images to learn how.

install new packages

npm install gatsby-plugin-image gatsby-plugin-sharp gatsby-transformer-sharp
gatsby-config.js
module.exports = {
  plugins: [
    `gatsby-plugin-image`,  // 追記
    `gatsby-plugin-sharp`,
    `gatsby-transformer-sharp`,
  ],
}

マイグレートコマンド

自動で置き換えてくれるコマンドを実行するとソース内のコードが自動で書き換えられます。
$ npx gatsby-codemods gatsby-plugin-image

# 最後に出るメッセージ
All done. 
Results: 
0 errors
205 unmodified
0 skipped
11 ok
Time elapsed: 47.080seconds

画像読み込みまでの間仮表示される背景色(placeholder)が黒くなるのを改善

gatsby-plugin-image では画像が読み込まれるまでの間レイアウトシフトが起きないように仮のデータ(placeholder)が表示されます。
placeholderは、デフォルトでドミナントカラー(配色全体を支配するような色相)が指定されています。
サイトで使用している画像がpngだからか黒背景で表示されてしまい目立つので変更しました。
プロパティに透過が有効になるTRACED_SVGを指定。
その他にも、ぼやけて表示させる BLURRED や、placeholder自体を無効にする NONE が指定可能です。
// jsx
<StaticImage src="../images/logo.png" placeholder='TRACED_SVG' alt="ロゴマーク" />

// Graphql
childImageSharp {
	gatsbyImageData(width: 640, quality: 90, layout: CONSTRAINED, placeholder:TRACED_SVG, formats: [AUTO, WEBP, AVIF])
}
これで画像読み込み中に背景色が表示されなくなりました。

その他変更した箇所

gatsby-cliをアップデート

バージョンが古かったのでcliもアップデートしました。
# エラーが表示された
Update available 2.12.87 → 3.4.0  
Run npm i -g gatsby-cli to update

$ npm i -g gatsby-cli to update  # アップデートコマンド

Imported JSX component *** must be in PascalCase

コンポーネント名を修正

SEO というコンポーネントを使用できていたのですが、v3からはパスカルケースへ変更するように警告が出るようになりました。
SEOSeoに修正して対応しました。
// エラー内容
Imported JSX component SEO must be in PascalCase
💡
パスカルケースとは アッパーキャメルケースのこと。 EX) userName → UserName

V3にして変わったこと

v3に移行してからビルド時間が体感でわかるほど早くなりました。
Lighthouseのスコアもあがり、画像最適化によって画像表示パフォーマンスも向上するので開発者だけではなくサイトを使用するユーザーにもメリットがある変更でした。
使っているプラグインや環境によって対処方法が違うと思いますが、今回の作業が役に立てば幸いです。
コロのicon
コロ
飼い猫と食べ物のことを考えてたら1日が終わってます。Reactでいろいろ作りたい