microCMS JavaScript SDK

English README

JavaScriptやNode.jsのアプリケーションからmicroCMSのAPIと簡単に通信できます。

保守方針

このSDKの現在の保守レベルはActiveです。

詳細はSDKの保守方針をご覧ください。

チュートリアル

公式ドキュメントの チュートリアルをご覧ください。

はじめに

インストール

Node.js

$ npm install microcms-js-sdk

または

$ yarn add microcms-js-sdk

[!IMPORTANT] v3.0.0以上を使用する場合は、Node.jsのv18以上が必要です。

ブラウザ（セルフホスティング）

リリースページからmicrocms-js-sdk-x.y.z.tgzをダウンロードして解凍してください。その後、お好みのサーバーにアップロードして使用してください。対象ファイルは ./dist/umd/microcms-js-sdk.js です。

<script src="./microcms-js-sdk.js"></script>

ブラウザ（CDN）

外部プロバイダーが提供するURLを読み込んでご利用ください。

<script src="https://cdn.jsdelivr.net/npm/[email protected]/dist/umd/microcms-js-sdk.min.js"></script>

または

<script src="https://cdn.jsdelivr.net/npm/microcms-js-sdk/dist/umd/microcms-js-sdk.min.js"></script>

[!WARNING] ホスティングサービス（cdn.jsdelivr.net）はmicroCMSとは関係ありません。本番環境でのご利用には、お客様のサーバーでのセルフホスティングをお勧めします。

コンテンツAPI

インポート

Node.js

const { createClient } = require('microcms-js-sdk'); // CommonJS

または

import { createClient } from 'microcms-js-sdk'; //ES6

ブラウザ

<script>
  const { createClient } = microcms;
</script>

クライアントオブジェクトの作成

// クライアントオブジェクトを作成します。
const client = createClient({
  serviceDomain: 'YOUR_DOMAIN', // YOUR_DOMAINはXXXX.microcms.ioのXXXXの部分です。
  apiKey: 'YOUR_API_KEY',
  // retry: true // 最大2回まで再試行します。
});

APIメソッド

以下の表は、microCMS JavaScript SDKの各メソッドがリスト形式のAPIまたはオブジェクト形式のAPI、どちらで使用できるかを示しています。

| メソッド | リスト形式 | オブジェクト形式 | |-------------------|-------------|---------------| | getList | ✔️ | | | getListDetail | ✔️ | | | getObject | | ✔️ | | getAllContentIds | ✔️ | | | getAllContents | ✔️ | | | create | ✔️ | | | update | ✔️ | ✔️ | | delete | ✔️ | |

[!NOTE]

• 「リスト形式」の✔️は、APIの型がリスト形式に設定されている場合に使用できるメソッドを示します。
• 「オブジェクト形式」の✔️は、APIの型がオブジェクト形式に設定されている場合に使用できるメソッドを示します。

コンテンツ一覧の取得

getListメソッドは、指定されたエンドポイントからコンテンツ一覧を取得するために使用します。

client
  .getList({
    endpoint: 'endpoint',
  })
  .then((res) => console.log(res))
  .catch((err) => console.error(err));

queriesプロパティを使用したコンテンツ一覧の取得

queriesプロパティを使用して、特定の条件に一致するコンテンツ一覧を取得できます。利用可能な各プロパティの詳細については、microCMSのドキュメントを参照してください。

client
  .getList({
    endpoint: 'endpoint',
    queries: {
      draftKey: 'abcd',
      limit: 100,
      offset: 1,
      orders: 'createdAt',
      q: 'こんにちは',
      fields: 'id,title',
      ids: 'foo',
      filters: 'publishedAt[greater_than]2021-01-01T03:00:00.000Z',
      depth: 1,
    }
  })
  .then((res) => console.log(res))
  .catch((err) => console.error(err));

単一コンテンツの取得

getListDetailメソッドは、指定されたエンドポイントから、IDで指定された単一コンテンツを取得するために使用します。

client
  .getListDetail({
    endpoint: 'endpoint',
    contentId: 'contentId',
  })
  .then((res) => console.log(res))
  .catch((err) => console.error(err));

queriesプロパティを使用した単一コンテンツの取得

queriesプロパティを使用して、特定の条件に一致する単一コンテンツを取得できます。利用可能な各プロパティの詳細については、microCMSのドキュメントを参照してください。

client
  .getListDetail({
    endpoint: 'endpoint',
    contentId: 'contentId',
    queries: {
      draftKey: 'abcd',
      fields: 'id,title',
      depth: 1,
    }
  })
  .then((res) => console.log(res))
  .catch((err) => console.error(err));

オブジェクト形式のコンテンツの取得

getObjectメソッドは、指定されたエンドポイントからオブジェクト形式のコンテンツを取得するために使用します。

client
  .getObject({
    endpoint: 'endpoint',
  })
  .then((res) => console.log(res))
  .catch((err) => console.error(err));

コンテンツIDの全件取得

getAllContentIdsメソッドは、指定されたエンドポイントからコンテンツIDのみを全件取得するために使用します。

client
  .getAllContentIds({
    endpoint: 'endpoint',
  })
  .then((res) => console.log(res))
  .catch((err) => console.error(err));

filtersプロパティを使用したコンテンツIDの全件取得

filtersプロパティを使用することで、条件に一致するコンテンツIDを全件取得できます。

client
  .getAllContentIds({
    endpoint: 'endpoint',
    filters: 'category[equals]uN28Folyn',
  })
  .then((res) => console.log(res))
  .catch((err) => console.error(err));

下書き中のコンテンツのIDを全件取得

draftKeyプロパティを使用することで、下書き中のコンテンツのIDを全件取得できます。

client
  .getAllContentIds({
    endpoint: 'endpoint',
    draftKey: 'draftKey',
  })
  .then((res) => console.log(res))
  .catch((err) => console.error(err));

コンテンツID以外のフィールドの値を全件取得

alternateFieldプロパティにフィールドIDを指定することで、コンテンツID以外のフィールドの値を全件取得できます。

client
  .getAllContentIds({
    endpoint: 'endpoint',
    alternateField: 'url',
  })
  .then((res) => console.log(res))
  .catch((err) => console.error(err));

コンテンツの全件取得

getAllContentsメソッドは、指定されたエンドポイントから、コンテンツを全件取得するために使用します。

client
  .getAllContents({
    endpoint: 'endpoint',
  })
  .then((res) => console.log(res))
  .catch((err) => console.error(err));

queriesプロパティを使用したコンテンツの全件取得

queriesプロパティを使用して、特定の条件に一致するすべてのコンテンツを取得できます。利用可能な各プロパティの詳細については、microCMSのドキュメントを参照してください。

client
  .getAllContents({
    endpoint: 'endpoint',
    queries: { filters: 'createdAt[greater_than]2021-01-01T03:00:00.000Z', orders: '-createdAt' },
  })
  .then((res) => console.log(res))
  .catch((err) => console.error(err));

コンテンツの登録

createメソッドは指定されたエンドポイントにコンテンツを登録するために使用します。

client
  .create({
    endpoint: 'endpoint',
    content: {
      title: 'タイトル',
      body: '本文',
    },
  })
  .then((res) => console.log(res.id))
  .catch((err) => console.error(err));

IDを指定してコンテンツを登録

contentIdプロパティを使用することで、指定されたIDでコンテンツを登録できます。

client
  .create({
    endpoint: 'endpoint',
    contentId: 'contentId',
    content: {
      title: 'タイトル',
      body: '本文',
    },
  })
  .then((res) => console.log(res.id))
  .catch((err) => console.error(err));

下書き中のステータスでコンテンツを登録

isDraftプロパティを使用することで、下書き中のステータスでコンテンツを登録できます。

client
  .create({
    endpoint: 'endpoint',
    content: {
      title: 'タイトル',
      body: '本文',
    },
    isDraft: true,
  })
  .then((res) => console.log(res.id))
  .catch((err) => console.error(err));

指定されたIDかつ下書き中のステータスでコンテンツを登録

contentIdプロパティとisDraftプロパティを使用することで、指定されたIDかつ下書き中のステータスでコンテンツを登録できます。

client
  .create({
    endpoint: 'endpoint',
    contentId: 'contentId',
    content: {
      title: 'タイトル',
      body: '本文',
    },
    isDraft: true,
  })
  .then((res) => console.log(res.id))
  .catch((err) => console.error(err));

公開終了のステータスでコンテンツを登録

isClosedプロパティを使用することで、公開終了のステータスでコンテンツを登録できます。

注: isDraft と isClosed は同時に true にできません。両方を true で渡すと、SDK はランタイムでエラーとして拒否します。isClosed: true を使う場合は、isDraft を省略、または false を設定してください。

client
  .create({
    endpoint: 'endpoint',
    content: {
      title: 'タイトル',
      body: '本文',
    },
    isClosed: true,
  })
  .then((res) => console.log(res.id))
  .catch((err) => console.error(err));

指定されたIDかつ公開終了のステータスでコンテンツを登録

contentIdプロパティとisClosedプロパティを使用することで、指定されたIDかつ公開終了のステータスでコンテンツを登録できます。上記と同様、isDraft と isClosed を同時に true にすることはできません。

client
  .create({
    endpoint: 'endpoint',
    contentId: 'contentId',
    content: {
      title: 'タイトル',
      body: '本文',
    },
    isClosed: true,
  })
  .then((res) => console.log(res.id))
  .catch((err) => console.error(err));

コンテンツの編集

updateメソッドは特定のコンテンツを編集するために使用します。

client
  .update({
    endpoint: 'endpoint',
    contentId: 'contentId',
    content: {
      title: 'タイトル',
    },
  })
  .then((res) => console.log(res.id))
  .catch((err) => console.error(err));

コンテンツの下書き更新

isDraft プロパティを指定することで、コンテンツを下書き状態で更新することができます。

client
  .update({
    endpoint: 'endpoint',
    contentId: 'contentId',
    content: {
      title: 'タイトル',
    },
    isDraft: true,
  })
  .then((res) => console.log(res.id))
  .catch((err) => console.error(err));

オブジェクト形式のコンテンツの編集

APIの型がオブジェクト形式のコンテンツを編集する場合は、contentIdプロパティを使用せずに、エンドポイントのみを指定します。

client
  .update({
    endpoint: 'endpoint',
    content: {
      title: 'タイトル',
    },
  })
  .then((res) => console.log(res.id))
  .catch((err) => console.error(err));

コンテンツの削除

deleteメソッドは指定されたエンドポイントから特定のコンテンツを削除するために使用します。

client
  .delete({
    endpoint: 'endpoint',
    contentId: 'contentId',
  })
  .catch((err) => console.error(err));

TypeScript

getListメソッド、getListDetailメソッド、getObjectメソッドはデフォルトのレスポンスの型を定義しています。

getListメソッドのレスポンスの型

type Content = {
  text: string,
};
/**
 * {
 *  contents: Content[]; // 設定したスキーマの型を格納する配列
 *  totalCount: number;
 *  limit: number;
 *  offset: number;
 * }
 */
client.getList<Content>({ /* その他のプロパティ */ })

getListDetailメソッドのレスポンスの型

type Content = {
  text: string,
};
/**
 * {
 *  id: string;
 *  createdAt: string;
 *  updatedAt: string;
 *  publishedAt?: string;
 *  revisedAt?: string;
 *  text: string; // 設定したスキーマの型
 * }
 */
client.getListDetail<Content>({ /* その他のプロパティ */ })

getObjectメソッドのレスポンスの型

type Content = {
  text: string,
};
/**
 * {
 *  createdAt: string;
 *  updatedAt: string;
 *  publishedAt?: string;
 *  revisedAt?: string;
 *  text: string; // 設定したスキーマの型
 * }
 */
client.getObject<Content>({ /* その他のプロパティ */ })

getAllContentIdsメソッドのレスポンスの型

/**
 * string[]
 */
client.getAllContentIds({ /* その他のプロパティ */ })

型安全なコンテンツの登録

contentの型はContentであるため、型安全なコンテンツの登録が可能です。

type Content = {
  title: string;
  body?: string;
};

client.create<Content>({
  endpoint: 'endpoint',
  content: {
    title: 'タイトル',
    body: '本文',
  },
});

型安全なコンテンツの編集

contentはPartial<Content>型であるため、編集したいプロパティだけを渡せます。

type Content = {
  title: string;
  body?: string;
};

client.update<Content>({
  endpoint: 'endpoint',
  content: {
    body: '本文',
  },
});

CustomRequestInit

Next.js App Router

Next.jsのApp Routerで利用されるfetchのcacheオプションを指定できます。

指定可能なオプションは、Next.jsの公式ドキュメントを参照してください。

Functions: fetch | Next.js

const response = await client.getList({
  customRequestInit: {
    next: {
      revalidate: 60,
    },
  },
  endpoint: 'endpoint',
});

AbortController: abortメソッド

fetchリクエストを中断できます。

const controller = new AbortController();
const response = await client.getObject({
  customRequestInit: {
    signal: controller.signal,
  },
  endpoint: 'config',
});

setTimeout(() => {
  controller.abort();
}, 1000);

マネジメントAPI

インポート

Node.js

const { createManagementClient } = require('microcms-js-sdk'); // CommonJS

または

import { createManagementClient } from 'microcms-js-sdk'; //ES6

ブラウザ

<script>
  const { createManagementClient } = microcms;
</script>

クライアントオブジェクトの作成

const client = createManagementClient({
  serviceDomain: 'YOUR_DOMAIN', // YOUR_DOMAINはXXXX.microcms.ioのXXXXの部分です。
  apiKey: 'YOUR_API_KEY',
});

メディアのアップロード

メディアに画像やファイルをアップロードできます。

Node.js

// Blob
import { readFileSync } from 'fs';

const file = readFileSync('path/to/file');
client
  .uploadMedia({
    data: new Blob([file], { type: 'image/png' }),
    name: 'image.png',
  })
  .then((res) => console.log(res))
  .catch((err) => console.error(err));

// or ReadableStream
import { createReadStream } from 'fs';
import { Stream } from 'stream';

const file = createReadStream('path/to/file');
client
  .uploadMedia({
    data: Stream.Readable.toWeb(file),
    name: 'image.png',
    type: 'image/png',
  })
  .then((res) => console.log(res))
  .catch((err) => console.error(err));

// or URL
client
  .uploadMedia({
    data: 'https://example.com/image.png',
    // name: 'image.png', ← 任意
  })
  .then((res) => console.log(res))
  .catch((err) => console.error(err));

ブラウザ

// File
const file = document.querySelector('input[type="file"]').files[0];
client
  .uploadMedia({
    data: file,
  })
  .then((res) => console.log(res))
  .catch((err) => console.error(err));

// or URL
client
  .uploadMedia({
    data: 'https://example.com/image.png',
    // name: 'image.png', ← 任意
  })
  .then((res) => console.log(res))
  .catch((err) => console.error(err));

TypeScript

uploadMediaメソッドのパラメータの型

type UploadMediaRequest =
  | { data: File }
  | { data: Blob; name: string }
  | { data: ReadableStream; name: string; type: `image/${string}` }
  | {
      data: URL | string;
      name?: string | null | undefined;
      customRequestHeaders?: HeadersInit;
    };
function uploadMedia(params: UploadMediaRequest): Promise<{ url: string }>;

エラーハンドリング

microCMS APIへのリクエストに失敗した場合、エラーは通常のErrorとして扱えます。console.error(error)でエラーメッセージとスタックトレースを出力でき、HTTPエラーの場合はHTTPステータスとAPIから返されたエラーメッセージも含まれます。

さらに、isMicroCMSRequestErrorでエラーを判定すると、リクエストに関する追加情報としてstatus、url、originalErrorを個別に参照できます。

import { createClient, isMicroCMSRequestError } from 'microcms-js-sdk';

const client = createClient({
  serviceDomain: 'serviceDomain',
  apiKey: 'apiKey',
});

try {
  await client.getList({ endpoint: 'blog' });
} catch (error) {
  // エラーメッセージとスタックトレースを出力します
  console.error(error);

  if (isMicroCMSRequestError(error)) {
    // 必要に応じてリクエストに関する追加情報を参照できます
    console.log(error.status);
    console.log(error.url);
    console.log(error.originalError);
  }
}

| プロパティ | HTTPエラー | ネットワークエラー | | --------------- | ----------------------------- | --------------------------- | | status | HTTPステータスコード | undefined | | url | リクエスト先URL | リクエスト先URL | | originalError | undefined | fetchが投げた元の値 |

urlにdraftKeyが含まれる場合、その値は***にマスクされます。リクエストヘッダー、リクエストボディ、Responseオブジェクトはエラーへ追加されません。

originalErrorの内容はNode.js、ブラウザ、Edge Runtimeなどの実行環境によって異なり、SDKとして形式を保証しません。

追加されるプロパティは非列挙です。そのため、既存のmessage、toString()、Object.keys()、JSON.stringify()の結果には影響しません。

ヒント

読み取り用と書き込み用で別々のAPIキーを使用する

const readClient = createClient({
  serviceDomain: 'serviceDomain',
  apiKey: 'readApiKey',
});
const writeClient = createClient({
  serviceDomain: 'serviceDomain',
  apiKey: 'writeApiKey',
});

ライセンス

Apache-2.0