TypeScript 
はじめに
こんにちは、microCMSでプロダクトマネージャーをしている清水です。
このたび、microCMSのAPIスキーマからTypeScriptの型を自動生成するツール「microcms-typegen」を公開しました。
型の自動生成は、microCMSのサービス提供初期からご要望をいただいていた機能です。
対応までに長くお待たせしてしまい、申し訳ありません・・！
マネジメントAPIでAPIのスキーマ情報を取得できるようになったことで、その情報をもとに型を自動生成する仕組みを提供できるようになりました。
あわせて、JavaScript SDK「microcms-js-sdk」では、生成した型をクライアントに指定することで、エンドポイントや取得クエリに応じた型推論を利用できるようになりました（ver 3.6.0）。
型定義の作成からAPI呼び出し時の型指定まで、TypeScriptでmicroCMSを利用する際の手間を減らせるアップデートです。
各ツールのリポジトリはこちらです。導入手順や詳しい使い方も、それぞれのREADMEで確認できます。
使い方
まずはSDKで生成した型を利用する例を紹介し、その後に型を生成する手順を説明します。
SDKで生成した型を利用する
以下は、blogsというAPIにtitleフィールドと、カテゴリーへの参照フィールドcategoryがある場合の例です。
import { createClient } from 'microcms-js-sdk';
import type { MainServiceSchema } from './microcms-types';
const client = createClient<MainServiceSchema>({
serviceDomain: 'YOUR_DOMAIN',
apiKey: 'YOUR_API_KEY',
});
const response = await client.getList({
endpoint: 'blogs',
queries: {
depth: 2,
fields: ['title', 'category.name'],
},
});MainServiceSchemaは、microcms-typegenで生成したサービス全体の型です。
この型をcreateClientに指定すると、getList<Blog>のように、呼び出しごとにコンテンツの型を指定する必要がなくなります。
戻り値の型は、エンドポイントだけでなく、fieldsによる取得項目の絞り込みや、depthによる参照先の展開も反映して推論されます。
また、存在しないエンドポイントやフィールドを指定した場合には、TypeScriptの型エラーとして確認できます。実行する前に誤りに気づきやすくなります。
コンテンツの作成・更新にも対応
型推論は、コンテンツの取得だけでなく、作成・更新でも利用できます。
await client.update({
endpoint: 'blogs',
contentId: 'blog-id',
content: {
title: '更新したタイトル',
},
});エンドポイントに応じて、書き込むフィールド名や値の型が推論されます。読み取りと書き込みの両方で、補完と型検査を利用しながら実装を進められます。
なお、型検査はTypeScriptのコンパイル時に行われます。filtersやordersの文字列内に指定するフィールド名など、一部の項目は検査の対象外です。詳しい対応範囲は、JavaScript SDKのREADMEをご確認ください。
APIスキーマから型を生成する
続いて、SDKに指定する型を生成する方法を紹介します。
これまでTypeScriptでmicroCMSを利用する際は、管理画面で設定したAPIスキーマに合わせて、コンテンツの型を自分で定義する必要がありました。
フィールドを追加・変更した場合には型定義も更新し、取得する項目や参照の深さを変えた場合には、戻り値の型との整合性も確認する必要があります。
microcms-typegenは、マネジメントAPIから取得したスキーマをもとに、SDKで利用する型を生成します。管理画面の設定を見ながら型を書き写す作業を減らし、APIスキーマに沿った型定義を用意できます。
スキーマを変更した場合も、コマンドを再実行することで型を更新できます。
導入するプロジェクトで、ツールのインストールと初期設定を行います。
npm install -D microcms-typegen
npx microcms-typegen init続いて、「API情報の取得」権限を持つAPIキーを用意し、.envにサービスIDとAPIキーを設定します。
MICROCMS_SERVICE_DOMAIN=your-service
MICROCMS_API_INFO_API_KEY=your-api-info-api-key作成されたmicrocms-typegen.config.tsで出力先を確認し、次のコマンドを実行します。
npx microcms-typegen generate生成されたサービス型を、先ほどの例のようにSDKのcreateClientへ指定すれば準備は完了です。
また、生成済みの型と現在のAPIスキーマに差分があるかを確認するcheckコマンドも用意しています。CIに組み込むことで、型の更新漏れを検知できます。
動作環境や詳しい設定方法は、型生成ツールのREADMEをご確認ください。
おわりに
今回は、TypeScriptの型生成ツールと、JavaScript SDKの型推論の強化についてご紹介しました！
APIスキーマから型を生成し、その型を使って取得・更新処理を記述できるようになりました。
AIを活用した開発でも、この仕組みが役立つと考えています。実際のAPIスキーマから生成した型を使うことで、AIが存在しないエンドポイントやフィールドを指定した場合にも、型エラーとして検知できます。型検査の結果をAIに返し、修正を促すサイクルに組み込むこともできます。
今回の型生成とSDKの型検査が、AIを活用した開発の安全性を高める「ハーネス」としても機能することを期待しています！
TypeScriptでmicroCMSを利用している方は、ぜひお試しください！
また、今回の開発にあたっては、ユーザーの方が開発・公開されているmicrocms-ts-sdkも参考にさせていただきました。microCMSをより使いやすくするための取り組みを公開し、コミュニティに還元してくださっていることに、感謝申し上げます。
