contentful-typescript-codegenからcf-content-types-generatorに移行する

cf-content-types-generatorへ移行した理由

typescript環境でContent Delivery APIを使用してコンテンツを取得するとき、取得したコンテンツの型をモデルの数だけ定義するのは手間がかかります。
幸いにもコンテンツの型を自動で生成するライブラリはいくつかあり、私はcontentful-typescript-codegenを愛用していました。
このライブラリを採用したのは2022年初頭くらいで、この頃のcontentful.jsのパッケージのバージョンはv9でした。

しかし、このライブラリのメンテナンスが最近行われておらず、2024年の10月現在、contentful.jsのv10の型に対応していません。
v10にアップデートすることでより型が厳格になり、バグが発生しにくくなるのですが、v10が公開されて1年以上経ちましたがアップデートされる気配がなかったので別のライブラリである
cf-content-types-generatorに置き換えることにしました。
おそらく上記の理由でcontentful-typescript-codegenは使われなくなり、npmのダウンロード数も現在は逆転しています。

cf-content-types-generatorを使って型を生成する流れ

contentful-typescript-codegenを使って型の生成をするには、同時にcontentful-cliも使用する必要があります。
contentful-cliはContentgulの操作をコマンドラインで行うことができるツールであり、モデルやコンテンツの操作を行うことができますが、今回必要になるのは space exportコマンドです。
このコマンドを実行することでモデルのフィールド構成をJSONで出力することができます。
上記のcontentful-cliで出力したJSONファイルを元にcf-content-types-generatorを使用して型ファイルを作成することができます。

contentful-cliを使用してモデルのフィールド構成をJSONファイルとして出力する

Content Management APIのトークンを用意する

contentful-cliを使用するにはContent Management APIのトークンが必要になるので事前に用意します。
「Contentfulで記事やアセットを一括エクスポート/インポートする方法」の記事や、公式ドキュメントの「Authentication」を参考にすると作成できると思います。
うまく作成できれば、「CFPAT-*****」といった形式のトークンを入手できると思います。

JSONファイルを出力する

contentful-cliをプロジェクトにインストールします。

$ npm install -D contentful-cli

package.jsonのscriptsにJSONファイルを出力するため、contentful space exportコマンドを追加します。
このとき、出力するJSONファイルをカスタマイズしたいので、コマンドの引数にexport-config.jsonというファイルを指定しています。

package.json

{
   ...
   "scripts": {
      "contentful-export": "contentful space export --config export-config.json",
   }
   ...
}

上記のexport-config.jsonの中身は以下のようにします。

{
  "spaceId": "space-id",
  "contentFile": "contentful-export.json",
  "skipContent": true,
  "skipRoles": true,
  "skipWebhooks": true,
  "skipTags": true
}

それぞれのパラメータの詳細は「Importing and exporting content with the Contentful CLI」のページの「You can find a reference config file here.」の部分のリンクから飛んだページに記載されています。
ポイントとして、出力するデータの中から必要ないものを削っています。
何の指定もせずにspace exportコマンドで出力されたJSONファイルには、Entry、Tag、Roleなどのデータも含まれるため、JSONファイルを生成するまでの時間が長くなります。
cf-content-types-generatorで型を生成するのに必要なのはcontentTypesだけなので、他のものの取得はスキップするようにしています。

上記の設定が完了したら、以下のコマンドを実行します。
「--management-token」で渡すトークンは「Content Management APIのトークンを用意する」で生成したContent Management APIのトークンです。
このトークンはexport-config.jsonに記載してもいいですが、コミットに含めたくないのでコマンドの引数で渡すようにしています。

$ npm run contentful-export --management-token [CMA Token]

実行すると、export-config.jsonのcontentFileパラメータで設定したcontentful-export.jsonというファイルが生成されます。

cf-content-types-generatorを使って型を生成する

cf-content-types-generatorをインストールします。

$ npm install -D cf-content-types-generator

package.jsonに以下のコマンドを追加します。

package.json

{
   ...
   "scripts": {
      "contentful-export": "contentful space export --config export-config.json",
      "contentful-generate-types": "cf-content-types-generator contentful-export.json -o /types --v10 --response",
   }
   ...
}

「-o」オプションで型を出力するディレクトリを指定します。
「--v10」オプションで出力される型をcontentful.jsのv10に対応した型を出力します。
「--response」を指定するとcontentful.jsのv10に対応したレスポンスの型を出力します。v10ではレスポンスの型を厳格に定義することができるようになったのでそれに対応した型を追加で出力できます。詳しいことはこの記事では割愛します。

package.jsonにコマンドを追加後、以下のコマンドを実行します。

$ npm run contentful-generate-types

/typesディレクトリにモデルごとの型が出力されます。

以上で完了です。