トップ
チュートリアル
Astro

Getting Started

最終更新日: 2026/08/10

こちらのドキュメントでは、microCMSをAstroで利用するための手順を示します。
初めてAstroからmicroCMSをご利用になる場合は、まずこちらの手順をお試しください。

事前に確認が必要なこと

Astroで開発するために、Node.jsとnpmが必要です。ご自身の開発環境にインストールしてください。
microCMSのサービス作成が完了している必要があります。未実施の場合は、「はじめに」のドキュメントをご参照ください。

microCMSのセットアップ

まずは、microCMSで簡単なAPIを作成します。今回は、以下の構成で作成します。

APIの型：オブジェクト形式
エンドポイント：hello
フィールドの種類：テキストフィールド
フィールドID：text

APIの作成画面で、任意のAPI名とエンドポイントを入力します。
エンドポイントには、helloと入力してください。

次に、APIの型として「オブジェクト形式」を選択します。

最後にフィールドを設定します。今回は、以下のテキストフィールドを一つ作成します。

フィールドID：text
表示名：テキスト
種類：テキストフィールド

上記の設定でAPIを作成すると、コンテンツを入稿できる状態になります。
編集画面に移り、テキストフィールドに任意の値を入力して、コンテンツを公開します。
例として、以下の内容を入力します。

Hello, microCMS!!

これで、APIからコンテンツを取得できる状態になりました。
画面右上の「APIプレビュー」をクリックして、作成したAPIにアクセスし、JSON形式のレスポンスが返却されることを確認しましょう。

Astroプロジェクトの準備

次に、Astroのプロジェクトを作成します。
Astroが公式に提供しているCLIを利用します。ターミナルで、以下のコマンドを実行してください。

npm create astro@latest

npm create astro@latestを実行すると、Astroプロジェクトの作成に必要な項目が対話形式で表示されます。

今回は、以下の設定で進めます。

プロジェクトの作成先：astro-microcms
テンプレート：最小構成のテンプレート
依存パッケージのインストール：実行する
Gitリポジトリの初期化：任意

プロンプトの表示内容は、CLIのバージョンによって変更される場合があります。ご自身の環境に合わせて選択してください。

プロジェクトの作成が完了したら、プロジェクトのディレクトリに移動します。

cd astro-microcms

続いて、開発サーバーを起動します。

npm run dev

ブラウザから、http://localhost:4321 にアクセスします。
プロジェクトの作成に成功している場合、Astroの初期画面がブラウザに表示されます。

microcms-js-sdkの初期化

microCMSが公式に提供しているJavaScript SDKのmicrocms-js-sdkをインストールします。

npm install microcms-js-sdk

microcms-js-sdkを利用すると、createClient関数でクライアントを作成し、microCMSのAPIからコンテンツを取得できます。

環境変数の設定

プロジェクトのルートディレクトリに、.envファイルを作成します。

astro-microcms/
├── src/
├── .env
├── astro.config.mjs
└── package.json

.envファイルに、サービスドメインとAPIキーを設定します。

MICROCMS_SERVICE_DOMAIN=service-domain
MICROCMS_API_KEY=api-key

MICROCMS_SERVICE_DOMAINには、microCMSのサービスドメインを設定します。
たとえば、管理画面のURLが "https://example.microcms.io" である場合、サービスドメインには、exampleを指定します。

MICROCMS_API_KEYには、microCMSの管理画面で確認できるAPIキーを設定してください。

APIクライアントの作成

srcディレクトリ内にlibディレクトリを作成し、microcms.tsというファイルを作成します。

src/
├── lib/
│   └── microcms.ts
└── pages/
    └── index.astro

src/lib/microcms.tsに、以下のコードを記述します。

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

const serviceDomain = import.meta.env.MICROCMS_SERVICE_DOMAIN;
const apiKey = import.meta.env.MICROCMS_API_KEY;

if (!serviceDomain || !apiKey) {
  throw new Error(
    'MICROCMS_SERVICE_DOMAIN または MICROCMS_API_KEY が設定されていません。',
  );
}

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

createClient関数に、サービスドメインとAPIキーを渡して、microCMSのAPIクライアントを作成しています。

microCMSから情報を取得して表示

先ほど作成したmicroCMSのAPIから情報を取得し、画面に表示します。
src/pages/index.astroを、以下の内容に変更してください。

---
import { client } from '../lib/microcms';

type Hello = {
  text: string;
};

const data = await client.getObject<Hello>({
  endpoint: 'hello',
});
---

<html lang="ja">
  <head>
    <meta charset="UTF-8" />
    <meta
      name="viewport"
      content="width=device-width"
    />
    <title>Astro × microCMS</title>
  </head>
  <body>
    <main>
      <h1>{data.text}</h1>
    </main>
  </body>
</html>

Astroファイルの先頭にある、---で囲まれた部分をコンポーネントスクリプトと呼びます。
コンポーネントスクリプト内で、microCMSのAPIからコンテンツを取得しています。

今回作成したAPIはオブジェクト形式であるため、microcms-js-sdkのgetObjectメソッドを使用します。Hello型を指定することで、取得するtextフィールドの型も定義しています。

const data = await client.getObject<Hello>({
  endpoint: 'hello',
});

取得したデータのtextを、HTMLのh1要素に表示します。

<h1>{data.text}</h1>

開発サーバーを起動していない場合は、以下のコマンドを実行します。

npm run dev

ブラウザから http://localhost:4321 にアクセスしてください。
microCMSに入稿した内容が、画面に表示されます。

microCMSの管理画面でテキストを変更して公開し、ブラウザを再読み込みすると、表示内容が変わることも確認してみましょう。

最後に、本番用のビルドが正常に完了すれば、初期導入は完了です。

npm run build

事前に確認が必要なこと
microCMSのセットアップ
Astroプロジェクトの準備
microcms-js-sdkの初期化
環境変数の設定
APIクライアントの作成
microCMSから情報を取得して表示