This document outlines the steps to use microCMS with Astro.
If you are using microCMS from Astro for the first time, please try the following steps first.

Prerequisites

• You need Node.js and npm to develop with Astro. Please install them in your development environment.
• You must have completed the creation of a microCMS service. If you haven't done this, please refer to the "Getting Started" document.

Setting Up microCMS

First, let's create a simple API in microCMS. This time, we will create it with the following configuration.

• API Type: Object format
• Endpoint: hello
• Field Type: Text Field
• Field ID: text

In the API creation screen, enter any API name and endpoint.
Please enter hello for the endpoint.

Next, select "Object format" as the API type.

Finally, set up the field. This time, we will create one text field as follows.

• Field ID: text
• Display Name: Text
• Type: Text Field

Once you create the API with the above settings, you will be able to submit content.
Move to the editing screen, enter any value in the text field, and publish the content.
For example, enter the following content.

Hello, microCMS!!

Now, you are able to retrieve content from the API.
Click on "API Preview" in the upper right corner to access the created API and confirm that a JSON response is returned.

Preparing the Astro Project

Next, we will create an Astro project.
We will use the CLI officially provided by Astro. Please run the following command in your terminal.

npm create astro@latest

When you run npm create astro@latest, the necessary items for creating the Astro project will be displayed interactively.

This time, we will proceed with the following settings.

• Project creation destination: astro-microcms
• Template: Minimal template
• Install dependencies: Yes
• Initialize Git repository: Optional

The prompts may vary depending on the version of the CLI. Please choose according to your environment.

Once the project creation is complete, navigate to the project directory.

cd astro-microcms

Next, start the development server.

npm run dev

Access http://localhost:4321 from your browser.
If the project creation is successful, the initial screen of Astro will be displayed in the browser.

Initializing microcms-js-sdk

Install the JavaScript SDK microcms-js-sdk officially provided by microCMS.

npm install microcms-js-sdk

By using microcms-js-sdk, you can create a client with the createClient function and retrieve content from the microCMS API.

Setting Environment Variables

Create a .env file in the root directory of the project.

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

Set the service domain and API key in the .env file.

MICROCMS_SERVICE_DOMAIN=service-domain
MICROCMS_API_KEY=api-key

For MICROCMS_SERVICE_DOMAIN, set the service domain of microCMS.
For example, if the URL of the Administration console is "https://example.microcms.io", specify example as the service domain.

For MICROCMS_API_KEY, set the API key that can be confirmed in the microCMS Administration console.

Creating the API Client

Create a lib directory inside the src directory and create a file named microcms.ts.

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

Write the following code in 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 or MICROCMS_API_KEY is not set.',
  );
}

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

We are creating the microCMS API client by passing the service domain and API key to the createClient function.

Fetching and Displaying Information from microCMS

We will fetch information from the microCMS API we just created and display it on the screen.
Change src/pages/index.astro to the following content.

---
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>

The section at the top of the Astro file, surrounded by ---, is called the component script.
In the component script, we are fetching content from the microCMS API.

Since the API we created this time is in object format, we will use the getObject method of microcms-js-sdk. By specifying the Hello type, we also define the type of the text field to be retrieved.

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

The text of the retrieved data will be displayed in the HTML h1 element.

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

If the development server is not running, execute the following command.

npm run dev

Please access http://localhost:4321 from your browser.
The content submitted to microCMS will be displayed on the screen.

Change the text in the microCMS Administration console and publish it, then refresh the browser to confirm that the displayed content changes.

Finally, if the production build completes successfully, the initial setup is complete.

npm run build