ReproWorksLearning Product Studio
ブログ一覧へ

ブログ導入しました(MicroCMSの導入手順)

# Next.jsサイトにmicroCMSでブログを導入した手順と、つまずいたポイント

ReproWorksの公式サイトにブログ機能を追加しました。今回は、ヘッドレスCMSとして microCMS を使い、Next.js のサイトに記事一覧ページと記事詳細ページを組み込みました。

この記事では、実際に導入した流れ、設定時に間違えやすいポイント、これから microCMS を導入する人に向けたアドバイスをまとめます。

## microCMSを選んだ理由

ブログ機能を作る方法はいくつかあります。Markdownファイルをリポジトリ内で管理する方法、WordPressを使う方法、自前で管理画面を作る方法などです。

その中で microCMS を選んだ理由は、主に以下の3つです。

- 管理画面から記事を作成・更新できる

- Next.js 側では API で記事を取得するだけでよい

- サイトのデザインや構成を自由に作れる

特に、サイト本体は Next.js で自由に設計しつつ、記事の更新だけをCMS側で行える点が便利でした。コードを触らずに記事を追加できるため、日々の更新作業が軽くなります。

## 導入の大まかな流れ

今回の導入は、次の流れで進めました。

1. microCMSでサービスを作成する

2. ブログ用APIを作成する

3. APIキーとサービスドメインを取得する

4. Next.jsに microcms-js-sdk を追加する

5. 環境変数を設定する

6. 記事一覧ページを作る

7. 記事詳細ページを作る

8. ビルドして表示確認する

microCMS側では、ブログ用のAPIを作成します。今回はエンドポイント名を blog にしました。記事には、最低限以下のフィールドを用意しています。

フィールド

用途

title

記事タイトル

description

記事の概要

content

記事本文

tags

タグ

writer

著者

サイト側では、microCMS JavaScript SDK を使って記事を取得します。

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

const client = createClient({
  serviceDomain: process.env.MICROCMS_SERVICE_DOMAIN!,
  apiKey: process.env.MICROCMS_API_KEY!
});

一覧取得では getList を使います。

const blogs = await client.getList({
  endpoint: "blog",
  queries: {
    orders: "-publishedAt",
    limit: 100
  }
});

詳細ページでは、記事IDを使って getListDetail で1件取得します。

const blog = await client.getListDetail({
  endpoint: "blog",
  contentId
});

環境変数の設定

microCMSの情報は、コードに直接書かず、環境変数として管理します。

MICROCMS_API_KEY=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
MICROCMS_SERVICE_DOMAIN=your-service-domain
MICROCMS_BLOG_ENDPOINT=blog
BASE_URL=http://localhost:3000

MICROCMS_API_KEY は microCMS の管理画面から取得できます。
MICROCMS_SERVICE_DOMAIN は https://xxxxx.microcms.io の xxxxx の部分です。

本番環境では、BASE_URL を本番ドメインに変更します。

BASE_URL=https://reproworks.app

開発環境と本番環境でURLが違うため、BASE_URL は環境ごとに分けるのが安全です。

一番つまずいたポイント：エンドポイント名

今回もっとも大きなつまずきは、microCMSのエンドポイント名でした。

コード側では最初、以下のように blogs を指定していました。

endpoint: "blogs"

しかし、microCMS側で実際に作成していたAPIのエンドポイントは blog でした。

この状態で /blog にアクセスすると、microCMS API が 404 を返し、Next.js側ではページが正常に表示されませんでした。ブラウザ上では真っ白に見えたため、最初はCSSやReactの描画エラーのように見えましたが、原因はAPIのエンドポイント不一致でした。

microCMSでは、管理画面で作成したAPIのエンドポイント名と、コード側の endpoint は完全に一致している必要があります。

// microCMS側のエンドポイントが blog の場合
endpoint: "blog"

これは非常に間違えやすいポイントです。
blog なのか、blogs なのか、news なのか、コードを書く前に必ず確認することをおすすめします。

APIキーとサービスドメインの注意点

次に注意したいのが、APIキーとサービスドメインです。

MICROCMS_SERVICE_DOMAIN には、通常 xxxxx のようなサービスドメインだけを設定します。
https://xxxxx.microcms.io 全体を入れると、実装によってはURLが崩れることがあります。

そのため、コード側で次のように正規化しておくと安心です。

function normalizeServiceDomain(value?: string) {
  if (!value) return undefined;

  return value
    .replace(/^https?:\/\//, "")
    .replace(/\.microcms\.io\/?$/, "")
    .replace(/\/$/, "");
}

これにより、環境変数に xxxxx と入れても、https://xxxxx.microcms.io と入れても動くようになります。

記事が公開されているか確認する

microCMSで記事を書いたのにサイトに表示されない場合は、まず以下を確認します。

  • 記事が「下書き」ではなく「公開」になっているか
  • APIキーに読み取り権限があるか
  • エンドポイント名が一致しているか
  • フィールド名がコード側と一致しているか
  • 本番環境に環境変数を設定しているか
  • キャッシュや再生成のタイミングで反映待ちになっていないか

特に、本番環境に MICROCMS_API_KEY や MICROCMS_SERVICE_DOMAIN を設定し忘れると、ローカルでは表示されるのに本番では表示されない、という状態になります。

フィールド名もコードと合わせる

microCMS側で description というフィールドを作った場合、コード側も description として扱う必要があります。

例えば、コード側で category を表示しようとしているのに、microCMS側には tags しかない場合、カテゴリは表示されません。

今回の実装では、以下のように category、tags、writer の順で表示ラベルを決めるようにしました。

function getBlogLabel(blog) {
  return blog.category?.name ?? blog.tags?.[0] ?? blog.writer ?? "";
}

このようにしておくと、microCMS側の構成が少し変わっても表示が崩れにくくなります。

これから導入する人へのアドバイス

これから microCMS を導入する場合は、最初から大きく作り込まず、まずは最小構成で動かすのがおすすめです。

最初に確認すべきことは、デザインではなく「APIから記事が取れるか」です。

const blogs = await client.getList({
  endpoint: "blog"
});

console.log(blogs);

この段階で記事一覧が取得できれば、あとは画面に表示するだけです。逆に、ここで取得できない場合は、デザインやルーティングを調整しても問題は解決しません。

また、エラーが出たときはブラウザだけで判断せず、サーバー側のログを見ることが大切です。今回のように、画面上は真っ白でも、実際には microCMS API の 404 が原因だった、ということがあります。

まとめ

microCMSを使うと、Next.jsのサイトにブログ機能を比較的シンプルに追加できます。サイト本体のデザインやルーティングはNext.jsで管理し、記事の作成や更新はmicroCMSの管理画面で行えるため、運用しやすい構成になります。

一方で、導入時にはいくつか注意点があります。

  • エンドポイント名を必ず確認する
  • APIキーとサービスドメインを環境変数で管理する
  • ローカル環境と本番環境の設定を分ける
  • microCMS側のフィールド名とコード側の型を合わせる
  • 記事が公開状態になっているか確認する
  • エラー時はブラウザだけでなくサーバーログも確認する

今回の導入では、エンドポイント名の blog と blogs の違いでつまずきました。小さな違いですが、API連携ではこのような文字列の不一致が大きな原因になります。

これから microCMS を導入する人は、まず最小構成でAPI取得を確認し、その後に一覧ページ、詳細ページ、デザイン、SEO設定を順番に整えていくとスムーズです。

参考