gatsby-source-prismicプラグインをv3からv4へマイグレーションしたときのメモ

  • GatsbyJS
  • Prismic

gatsby-source-prismicというGatsbyプロジェクトでPrismic.ioのリポジトリからデータ(記事等)を取得するためのプラグインがあります。基本的にPrismic.ioをデータソースとしたGatsbyのプロジェクトではほぼ必須のものです。

本サイトも利用しいるプラグインで、つい最近バージョン4がリリースされていることを知ったので、バージョン3からアップデートしてみました。その時の移行作業のメモを残しておこうと思います。

公式がドキュメントにまとめてくれているため、それを参考に作業を進めました。

📖 Migration Guide: gatsby-source-prismic V3 to V4

v4にアップデートするにあたって

もし、まだv2のgatsby-source-prismicを使っている場合は、v2 → v3 → v4という流れでアップデートを実施した方が良さそうです。

また、Gatsbyがv3でない場合もアップデートしてください。

v4の変更点の概要

公式のドキュメントからの抜粋です。

  • 複数のPrismic.ioリポジトリのサポート
  • カスタムタイプスキーマの自動フェッチ(2021年8月8日時点ではベータ機能らしい)
  • gatsby-plugin-imageプラグインのサポート
  • GraphQueryのサポート
  • プレビュー機能をgatsby-plugin-prismic-previewsプラグインへ分離

など、いくつか機能が拡張されたようです。

マイグレーション作業

私の場合は、プラグインオプションの一部とGraphQLクエリの一部を変更するぐらいの作業だけでした。

特にPrismic.ioで管理している画像ファイルをGatsbyImageで画像最適化しているような方やfetchLinksを利用している方は作業が多いかもしれません。

ここでは、私が作業した範囲のことを載せます。

カスタムタイプスキーマの定義

カスタムタイプスキーマとは、記事、ページコンテンツのフィールド定義と思っていただければと思います。

v3までは、例えば、PageBlogというカスタムタイプがPrismic.ioのリポジトリに定義されていても、Gatsbyプロジェクト上で型定義がBlogしか提供されていない場合は本来Pageのコンテンツに対して特に何も検証していない状態でした。この状態だとGraphQLのクエリを書く際に混乱しますし、型定義がないため正しく機能しません。

v4では、Prismic.ioのリポジトリ上のカスタムタイプスキーマをすべて提供することが必須になり、またプラグインはそれをリポジトリに対してチェックするようになりました。過去に一時的に使っていて、現在は削除して使っていないカスタムタイプがある場合は空のスキーマオブジェクトを渡せば良さそうです。

また、型定義をプラグインの設定(gatsby-config.js)に記述せず、Custom Types APIという機能を利用する方法でも良いです。

※2021年8月8日段階ではベータ機能。リポジトリで使いたい場合は連絡してとのことです。

ひとまず、しばらくはプラグインの設定に全カスタムタイプスキーマを指定しておきましょう。

module.exports = {
  plugins: [
    {
      resolve: 'gatsby-source-prismic',
      options: {
        repositoryName: '〜Prismic.ioのリポジトリ名〜',
        accessToken: '〜略〜',
        schemas: {
          // すべての型定義を列挙する (v3,v4で特に変わらない)
          blog: require('./prismic-custom-types/blog.json'),
        },
      },
    },
  ],
}

クエリの更新

GraphQLタイプのドキュメントおよびフィールドの名前に変更が入りました。

v3とv4の命名パターンを示します。

v3: Prismic{カスタムタイプ名}{フィールドID}

v4: Prismic{カスタムタイプ名}Data{フィールドID}

例えば、カスタムタイプ名がBlogでフィールドIDがBodyTextのときは次のようになります。

v3: PrismicBlogBodyText

v4: PrismicBlogDataBodyText

次に実際に変更したものを抜粋して示します。まずは変更前のもの。

import { graphql } from 'gatsby';

export const query = graphql`
  query ($uid: String!) {
    blog: prismicBlog(uid: { eq: $uid }) {
      uid
      data {
        title {
          text
        }
        body {
          ... on PrismicBlogBodyRichText {
            sliceType: slice_type
            primary {
              text: rich_text {
                raw
              }
            }
          }
        }
      }
    }
  }
`;

変更後を示します。

import { graphql } from 'gatsby';

export const query = graphql`
  query ($uid: String!) {
    blog: prismicBlog(uid: { eq: $uid }) {
      uid
      data {
        title {
          text
        }
        body {
          ... on PrismicBlogDataBodyRichText {
            sliceType: slice_type
            primary {
              text: rich_text {
                raw
              }
            }
          }
        }
      }
    }
  }
`;

以上、抜粋ですがこんな感じで変更になりました。

LinkResolverとHTMLSerializerの更新

プラグインのオプションにlinkResolverhtmlSerializerがあります。v3のときは指定時に余分な関数ラッパーが必要だったのですが、それが解消されました。(個人的に違和感があったので、v4でようやくスッキリしました)

const linkResolver = require('./src/modules/LinkResolver');

module.exports = {
  plugins: [
    {
      resolve: 'gatsby-source-prismic',
      options: {
        repositoryName: '〜Prismic.ioのリポジトリ名〜',
        accessToken: '〜略〜',
        schemas: {
          blog: require('./prismic-custom-types/blog.json'),
        },
        // 変更前: linkResolver: ({ node, key, value }) => (doc) => linkResolver(doc),
        linkResolver: (doc) => linkResolver(doc),
        // htmlSerializerは割愛しますが、似たような感じに変更できます。
      },
    },
  ],
}

おわりに

今回の場合はそこまで大変ではありませんでしたが、大規模で多くのカスタムタイプがあるようなプロジェクトだとマイグレーション作業は大変かと思います。特にGraphQLクエリ周りの変更は面倒で、テストもしっかりしておきたいところです。

将来的にバージョンアップでさらに使えるようになる機能もありそうなので、公式のマイグレーションガイドも追って更新されていくのだろうと思います。

この記事を共有

アバター

K.Utsunomiya
男・20代
主にWebフロントエンド技術と気になった音楽について投稿していきます。
最近ハマっていることは、クロスバイクで走ることとジムでの運動です。
詳しいプロフィール

© 2020–2021 コレ棚