🚪はじめに
こんにちは、管理人のTKGです。
当ブログ「PractiX Code Lab」は、これまでヘッドレスCMSの Newt を利用してきましたが、Newtのサービス終了に伴い、無料でも利用できるAPI上限が拡大した microCMS へ移行することを決定しました。
今回の移行は単なるデータ引っ越しではなく、両サービスのAPI設計思想の違いに起因するビルドエラーやテキスト崩れとの戦い――その全記録を共有します。
実際にNewtから引っ越しを検討されている方の参考になれば幸いです。
🗺️移行の全体像と戦略
- 計画・分析 – Newtで管理していた「記事／著者／タグ」3モデルの構造を完全に洗い出す
- 設計 – microCMSの機能（コンテンツ参照・オブジェクトフィールドなど）を活かし、APIスキーマを再設計
- 実装 –
/lib/microcms.tsを“変換アダプター”として実装し、フロントエンドUIの変更を最小化 - データ移行 – 記事16件はコンテンツ品質を見直しつつ手動再登録、タグはCSV変換スクリプトで一括登録
- テスト＆デプロイ – Vercelのプレビューデプロイで最終確認し、安全に本番へマージ
🧱直面した壁と乗り越え方
壁1：API仕様の微妙な違い（ビルドエラー祭り）
症状
npm run devでは正常でも、npm run buildでTypeScript型エラーが多発
主な原因
- ページネーションが
skipではなくoffset - OR検索が専用キーではなく
filtersパラメータで指定 idやtotalCountなどレスポンスに含まれるプロパティの型定義漏れ
解決策
- ビルドエラーと公式ドキュメントを突き合わせ、クエリ形式と型定義を修正
microcms-js-sdkの公式型（MicroCMSQueriesなど）を積極活用
学び
ビルドエラーはAPI仕様の理解不足を炙り出すレッドフラッグ。公式ドキュメントこそが常に信頼できる唯一の情報源。
壁2：最大の難関 ― リッチテキストの表示崩れ
症状
- microCMSのリッチテキストに入力したMarkdown見出し（
##）やテーブル（|）が、スタイル適用されずただの文字列として表示
原因究明
- DevToolsで確認すると、APIが
<h2>を返さず<p>## 見出し</p>のようにMarkdownを文字列のまま返却していた
解決策：Markdown-Firstへの転換
- CMS側 – リッチテキストをやめ、本文フィールドを 複数行テキスト に変更
- コンテンツ – 純粋なMarkdownをそのまま入力
- フロント –
react-markdown+remark-gfmでMarkdownをHTMLへ変換・描画
学び
CMSのリッチテキストは便利な一方、意図しないデータ形式を生むリスクもある。Markdown-First はシンプルで堅牢、かつ保守コストが低い。
壁3：Next.js App Routerの静的生成の罠
症状
- 本番デプロイ後、新規記事を追加してもページネーションの2ページ目で404
原因
generateStaticParamsとdynamicParams = falseの組み合わせで、ビルド時に存在しなかったページが拒否されていた
解決策
dynamicParams = trueへ設定し、アクセス時に動的生成を許可
✏️まとめ
- API差分は“アダプター”で吸収
- Markdown-First でリッチテキスト問題を根本解決
- ビルドエラーは理解不足を教えてくれるサイン
これらの教訓を経て、当ブログはより堅牢で運用しやすい技術基盤へ進化しました。この記事が、同じようにCMS移行に挑戦する誰かの助けになれば幸いです。
📎関連リンク
- microCMS公式ドキュメント （https://document.microcms.io/）
- Newt公式ドキュメント （https://www.newt.so/docs/app）
- Vercel Preview Deployments （https://vercel.com/docs/deployments/environments）
🏁おわりに
ヘッドレスCMSの移行は簡単ではありませんが、その過程には技術的な学びが詰まっています。この記事があなたの次のチャレンジへの道標になれば嬉しいです。
それでは、また！
Share this post