2026.09.22 プラットフォーム

Contentfulとは？API構成と料金の増え方・移行手順を実コードで解説

Q: Contentfulの日本語対応はどこまでできますか？

コンテンツ側の日本語はロケール機能で扱え、日本語を含む複数言語のフィールド値を1つのエントリに持てます。取得時は withAllLocales で全ロケールを含めるか、既定の単一ロケールで取るかを選べます。一方、管理画面のUIやドキュメントは英語が中心で、編集者向けの操作手順は日本語のマニュアルを自前で用意する前提で見積もるほうが安全です。

Q: Contentful CLIはどのコマンドから覚えればよいですか？

最初に使うのは contentful login と contentful space export の2つです。ログインは公式のOAuthサービス経由で行い、exportでスペースの内容をJSONへ書き出せます。この2つがあればバックアップが取れる状態になります。モデル変更をコードで管理する段階に入ったら contentful space migration を追加してください。CLIは 4.0.10 時点で Node.js 22以上を要求します。

Contentfulは、コンテンツを管理画面で編集し、APIで外部へ配信するヘッドレスCMSです。公式のJavaScriptクライアント contentful は2026年9月22日時点で 11.12.10 が最新で、実行環境としてNode.js 18以上が必要です。この記事では、配信・プレビュー・管理という3系統のAPIの役割、最小構成の取得コード、contentful-cliによるスペースの書き出しとマイグレーションDSLでのモデル変更、費用が増える変数、そして受託開発の現場で採用する条件と見送る場面までを、公式リポジトリの記述を根拠に整理します。管理画面の画面遷移ではなく、実装と移行の判断に必要な部分だけを扱います。

まとめ：Contentfulの採用条件と費用が跳ねる箇所

結論から書きます。Contentfulが向くのは、Webとアプリなど複数の出力先へ同じコンテンツを配信し、編集者と開発者が別チームに分かれている案件です。逆に、更新頻度が低く出力先が1サイトだけの案件では、API連携とモデル設計の工数が回収できません。

費用が跳ねるのは価格表の月額そのものではなく、ユーザー数・ロケール数・APIコール数の3つの変数。プロジェクト開始時に上限へ余裕があっても、多言語展開や外部システム連携を足した段階で段違いに増えます。契約前に、この3変数の1年後の見込みを数字で置いてください。

実装面では、公開用のContent Delivery API、下書き確認用のContent Preview API、更新用のContent Management APIが別トークンで分かれている点を最初に押さえると、後の権限設計が崩れません。

配信・プレビュー・管理の3系統に分かれるAPIとトークンの対応

Contentfulの実装でつまずく箇所は、機能の多さではなくAPIの系統分けにあります。用途ごとにエンドポイントとトークンが違い、混同すると本番で下書きが露出したり、逆に更新処理が401で止まったりします。

公開・下書き・更新で分かれる3つのAPIとトークンの対応関係

公式のJavaScriptクライアント contentful は、Content Delivery API と Content Preview API の2つを担当します。contentful.js の公式リポジトリでは、この2系統に加えて同期（Synchronization）、ロケール対応、リンク解決、レート制限時のリトライ処理が中核機能として明示されています。更新系は別パッケージの contentful-management が担当し、役割が重なりません。

API	用途	トークン	クライアント
Content Delivery API	公開済みの配信	CDAトークン	contentful
Content Preview API	下書きの確認	CPAトークン	contentful（host指定）
Content Management API	作成・更新・削除	CMAトークン	contentful-management

権限設計では、フロントエンドに渡してよいのはCDAトークンだけと決めておくと事故が減ります。CMAトークンはコンテンツの削除まで通るため、CIの秘密変数に閉じ込める前提で設計してください。

公式クライアントの最新版と要求されるNode.jsのバージョン

採用判断の前に、公式クライアントが要求するNode.jsのバージョンを確認しておくと、既存環境との衝突を早い段階で見つけられます。npm registry を2026年9月22日に参照した時点で、contentful は 11.12.10（2026-09-09公開）で engines に node 18以上、contentful-management は 12.17.0（2026-09-08公開）で node 20以上、contentful-cli は 4.0.10（2026-09-03公開）で node 22以上を宣言していました。3つのパッケージで要求バージョンが揃っていない点に注意が必要です。

ブラウザ側の対応範囲も揃っていません。contentful-management.js のリポジトリは Chrome 110以上、Firefox 110以上、Edge 110以上、Safari 16.4以上、Node.js の LTS を対応環境として挙げ、ES2023をサポートする環境が前提だと記しています。管理系の処理をブラウザで動かす設計にすると、この条件が効いてきます。

なお contentful は既定でESMとして配布され、CommonJS向けとブラウザ直読み込み向けのバンドルが別に用意されています。ビルド構成が古いプロジェクトへ後付けする場合、ここが最初の詰まりどころになります。

カーソル方式のページネーションと従来のskip指定との相違点

エントリを大量に取得する処理では、取得方式の選択が後から効いてきます。contentful.js はコレクション系のエンドポイントでカーソル方式のページネーションに対応しており、getEntriesWithCursor の応答に含まれる pages.next と pages.prev を次の要求へ渡す形です。

件数の多いスペースで skip 指定を使うと、後半のページほど応答が重くなり、取得途中にコンテンツが追加された場合に取りこぼしが起きます。カーソル方式はその両方を回避できる方式です。全件同期が目的なら、そもそも同期用のSyncエンドポイントを使う判断もあります。

GraphQL Content API を選ぶ道もあります。REST と GraphQL の性質差はGraphQLとREST APIの違いを整理した記事にまとめており、1画面で参照が深くネストするならGraphQL、単純な一覧取得ならRESTという切り分けが実務では扱いやすい判断軸です。

Node.js環境での初期設定とエントリ取得を通す最小コード手順

ここからは実際に動かす手順です。スペースIDとCDAトークンさえあれば、取得までは数分で通ります。

npmでの導入からcreateClientまでの初期設定の流れ

導入は1コマンド。クライアント生成時に渡す必須項目は、スペースIDとアクセストークンの2つだけです。以下は contentful.js のREADMEに記載された初期化手順を、コンテンツタイプ指定での一覧取得に置き換えたものです。

npm install contentful

import * as contentful from 'contentful'

const client = contentful.createClient({
  space: 'YOUR_SPACE_ID',
  accessToken: 'YOUR_CDA_TOKEN',
})

const entries = await client.getEntries({
  content_type: 'blogPost',
  limit: 10,
})

console.log(entries.items.length)

スペースはContentful上のプロジェクト単位の入れ物にあたり、トークンもスペース単位で発行されます。複数案件を1つのアカウントで扱う場合、スペースを分けるか環境を分けるかで権限の切り方が変わるため、この段階で方針を決めておくと後戻りが減ります。

プレビューAPIへ切り替えるhost指定と下書き表示の扱い方

下書きの確認画面を作るときは、別のクライアントを立てます。違いは2点で、アクセストークンをCPA用に変えることと、host に preview.contentful.com を指定することです。

const preview = contentful.createClient({
  space: 'YOUR_SPACE_ID',
  accessToken: 'YOUR_CPA_TOKEN',
  host: 'preview.contentful.com',
})

const draft = await preview.getEntries({
  content_type: 'blogPost',
})

プレビュー環境は検索エンジンに拾われない経路へ置く前提で設計してください。Next.jsで組む場合は、配信用のビルドとプレビュー用のレンダリングを分ける必要があり、どの描画方式を選ぶかで実装量が変わります。方式ごとの違いはNext.jsのレンダリング方式を比較した記事で整理しています。

リンク解決とロケール取得を切り替えるチェーン修飾子3種の使い方

Contentfulのエントリは他のエントリやアセットを参照でき、既定では参照先が解決された形で返ります。ただし参照先が未公開だとリンクオブジェクトのまま残り、フロント側で分岐が必要になる仕様です。contentful.js はこの挙動をチェーン修飾子で切り替えられます。

const resolved = await client.withoutUnresolvableLinks.getEntries()

const all = await client.withoutLinkResolution.withAllLocales.getEntries()

withoutUnresolvableLinks は解決できない参照を取り除き、withAllLocales は全ロケールを含めた形で返します。多言語サイトでは、1回の要求で全ロケールを取ってフロントで出し分けるか、ロケールごとに要求を分けるかでAPIコール数が変わります。後述する費用の変数に直結する選択です。

コンテンツモデルの移行とCLIでスペースを複製する実作業の手順

Contentfulの運用で効いてくるのは、管理画面での手作業ではなくコード化された移行手順です。本番と検証で同じモデルを保つ仕組みを最初に作れるかどうかで、半年後の運用コストが変わります。

contentful-cliの導入とスペースを書き出す実行コマンド

公式CLIはスペースの作成や削除に加え、スペースのJSONファイルへの書き出しと読み込み、マイグレーションスクリプトの実行、サンプルデータの投入を担当します。space export コマンドのドキュメントによると、既定の対象環境は master で、下書きやアーカイブ済みエントリは既定では書き出されません。

npm install -g contentful-cli

contentful login

contentful space export --space-id YOUR_SPACE_ID --environment-id master --export-dir ./backup

contentful space export --space-id YOUR_SPACE_ID --include-drafts true

バックアップ目的で使うなら include-drafts と include-archived を明示しないと、編集途中の原稿が落ちます。オプション名は environment-id であって environment ではない点も、スクリプト化のときに間違えやすい箇所です。

マイグレーションDSLでコンテンツモデルを段階的に変える記述例

モデル変更をコードで残す仕組みが contentful-migration です。公式リポジトリの記述どおり、マイグレーションファイルは migration オブジェクトを引数に取る関数をエクスポートする形になります。

module.exports = function (migration, context) {
  const dog = migration.createContentType('dog')
  const name = dog.createField('name')
  name.type('Symbol').required(true)
}

実行はCLI側に統合されており、space migration コマンドのドキュメントでは contentful space migration --space-id abcedef my-migration.js の形が例示されています。環境の既定値は master、--yes で確認をスキップ、--retry-limit で失敗時の再試行回数を指定できます。CIから流すときは --yes の指定が必要です。

環境（environment）を使った本番と検証の分離の作り方

Contentfulの環境はスペース内のコンテンツとモデルのコピーで、contentful.js では v6.0.0 以降が対応しています。運用の型としては、master を本番、staging を検証に割り当て、モデル変更は必ず検証環境へマイグレーションを流してから本番へ適用する順序にします。

この分離を作らずに本番のモデルを直接いじると、公開中の記事のフィールドが欠けた状態になり、フロント側が落ちます。環境数は契約プランの上限に含まれる項目なので、案件ごとに環境を増やす設計にすると、途中でプラン変更が必要になります。検証環境を1つに固定し、案件ごとの差分はマイグレーションファイルで管理する運用のほうが破綻しにくい形です。

Contentfulの料金で費用が膨らむ変数と見積り時の確認先

料金の議論は月額の数字だけでは終わりません。利用量で増える部分がどこかを把握してから契約しないと、公開の数か月後に上限へぶつかります。

無料枠で検証できる範囲と商用利用へ移行する前に確認する4条件

無料枠は、コンテンツタイプ数・レコード数・ユーザー数・ロケール数・環境数に上限が設けられた形で提供されています。技術検証には足りますが、商用案件へそのまま持ち込めるかは別問題です。契約前に確認すべきなのは次の4点。

無料枠の利用条件に商用利用の制限が含まれていないか
必要なロケール数と環境数が枠内に収まるか
編集に関わる人数が枠内のユーザー数を超えないか
本番トラフィックから想定されるAPIコール数が枠内か

上限値と条件は改定されるため、数字は提案書に転記せず、契約時点で公式の料金ページを開いて確認する運用にしてください。ここを過去案件の記憶で書くと、見積りが実態とずれます。

APIコール数・ユーザー数・ロケール数の3軸で費用が増える仕組み

費用が増える方向は3つに整理できます。まずAPIコール数。サーバーサイドレンダリングで毎回取得する構成にすると、アクセス数がそのままAPIコール数に跳ね返ります。静的生成と再検証を組み合わせれば、同じページビューでもコール数を桁で下げられます。

次にユーザー数。編集者だけでなくレビュー担当や外部ライターを招くと、席数の課金対象が増えます。最後にロケール数で、多言語展開はロケールの追加とコンテンツ量の増加が同時に起きるため、増え方が最も急です。

この3軸は契約後に減らしにくい性質を持ちます。多言語を1年以内に予定しているなら、単一言語での見積りを提示せず、ロケール追加後の金額で合意を取るほうが安全です。

受託開発でContentfulを採用する条件と見送るべき場面

ここからは判断の話です。技術的に使えることと、案件として採用すべきことは別に考えます。

採用してよい条件となる多チャネル配信と編集者の分業体制の有無

採用してよいのは、次の2つが揃う案件です。ひとつは配信先が複数あること。Webサイトに加えてアプリやデジタルサイネージ、あるいは別ブランドのサイトへ同じコンテンツを流す要件があるなら、APIで配信する構成が効きます。もうひとつは、編集する人と実装する人が別チームで、公開のたびにデプロイを挟めない体制であることです。

この2条件のうち片方しか満たさない案件では、既存のCMSで足ります。自社更新できる形でのサイト構築はWordPressサイト制作・CMS構築としても請けており、配信先が1つで編集者が数名なら、そちらのほうが初期費用も運用負荷も低く収まります。

見送るべき場面は更新頻度が低く単一サイトで完結する小規模案件

見送るべきなのは、更新が月数回、ページ数が数十、出力先が1サイトという構成の案件です。この規模だと、コンテンツモデルの設計、APIクライアントの実装、プレビュー環境の構築という3つの工数が、削減できる運用コストを上回ります。

もうひとつ見送る条件があります。編集者がWYSIWYGでの自由なレイアウト編集を求めている場合です。Contentfulは構造化されたフィールドにコンテンツを入れる思想のため、ページごとに見た目を変えたい要望とは噛み合いません。ここを握らずに提案すると、公開後に「前のCMSのほうが編集しやすい」という評価になります。

失敗パターンはモデル設計を固めないまま本番投入した後の運用崩れ

もっとも多い失敗は、コンテンツモデルを暫定のまま本番へ出し、運用開始後にフィールドを足し引きするパターンです。エントリが増えたあとのモデル変更は、マイグレーションスクリプトに加えて既存エントリの値の変換まで必要になり、作業量が初期設計の数倍に膨らみます。

回避策は工程の順序にあります。モデルの草案を作った段階で、実際の原稿を10〜20件入れてみて、フィールドが足りるか、逆に使われないフィールドが残らないかを検証してから本番スペースを作る。この一手間を入れるかどうかで、公開後半年の運用が変わります。

WordPressやSanity・Strapiとの使い分けと移行時の落とし穴

ヘッドレスCMSは選択肢が多く、Contentfulが常に第一候補になるわけではありません。既存資産と運用主体の2点で切り分けます。

WordPressから移す判断の分かれ目となる編集画面の要件

WordPressからの移行を検討する場面では、移行理由が表示速度なのか、配信先の追加なのかを先に確定させます。表示速度だけが課題なら、キャッシュ構成やインフラの見直しで解決する場合があり、CMS自体を替える必要はありません。

移行に踏み切る妥当な理由は、配信先が増えること、編集と公開の権限を細かく分けたいこと、そして本文以外の構造化データを扱いたいことの3つです。CMSの種類ごとの性質と発注時の判断材料は、ヘッドレスCMSと従来型CMSの違いを整理した記事で概念の側から扱っています。

Sanity・Strapiとの比較で見る運用主体とコストの差

同じヘッドレスCMSでも、運用の主体が違います。Contentfulは基盤の運用をベンダー側が持つSaaSで、サーバーの面倒を見る必要がない代わりに利用量で費用が決まる仕組みです。Strapiは自社サーバーへ置く選択ができ、インフラ運用を引き受ける代わりに利用量課金から離れられます。SanityはSaaS型でリアルタイム編集に強みがあり、Contentfulとの細かな差はSanity CMSとContentful・Strapiの違いを比較した記事で扱いました。

判断軸は単純です。インフラ運用を持てるチームがクライアント側にあるならStrapi、無いならContentfulかSanity。この線引きで候補は2つまで絞れます。

移行時に詰まるリッチテキストと参照フィールドの変換作業の注意点

既存CMSからの移行で工数が読みにくいのは、本文のリッチテキストと、記事間の参照です。WordPressの本文はHTMLの文字列ですが、Contentfulのリッチテキストは構造化されたJSONで保持されるため、単純なコピーでは移りません。見出し、リスト、画像、内部リンクのそれぞれに変換ルールが要ります。

参照フィールドも同様です。カテゴリやタグ、関連記事はエントリ間のリンクとして持つ設計になるため、移行スクリプトでは先にカテゴリを作り、IDを控えてから記事を投入する順序になります。この順序を守らないと、リンク先が見つからないエラーで止まります。移行は書き出し、変換、投入の3段階に分け、変換結果を検証環境で確認してから本番へ流してください。

よくある質問

Contentfulの導入検討でよく挙がる質問を、公式リポジトリの記載と実装上の判断に沿ってまとめました。

Contentfulは無料で使えますか？

無料で始められる枠が用意されており、コンテンツタイプ数やレコード数、ユーザー数、ロケール数、環境数に上限が設けられています。技術検証や個人の試用には足りますが、商用案件で使えるかは利用条件によります。上限値と条件は改定されるため、契約前に公式の料金ページで当日の内容を確認してください。無料枠のまま本番を走らせて上限に達すると、配信が止まるリスクがあります。

Contentfulの日本語対応はどこまでできますか？

コンテンツ側の日本語はロケール機能で扱え、日本語を含む複数言語のフィールド値を1つのエントリに持てます。取得時は withAllLocales で全ロケールを含めるか、既定の単一ロケールで取るかを選べます。一方、管理画面のUIやドキュメントは英語が中心で、編集者向けの操作手順は日本語のマニュアルを自前で用意する前提で見積もるほうが安全です。

ContentfulとWordPressはどちらを選ぶべきですか？

配信先が1つで、編集者がレイアウトまで自由に触りたい案件はWordPressが向きます。配信先が複数あり、コンテンツを構造化して他システムへも渡す要件があるならContentfulです。判断が割れるのは中間の案件で、その場合は1年後の配信先の数を基準にしてください。増える見込みが無いなら、移行コストを払う理由がありません。

Contentful CLIはどのコマンドから覚えればよいですか？

最初に使うのは contentful login と contentful space export の2つです。ログインは公式のOAuthサービス経由で行い、exportでスペースの内容をJSONへ書き出せます。この2つがあればバックアップが取れる状態になります。モデル変更をコードで管理する段階に入ったら contentful space migration を追加してください。CLIは 4.0.10 時点で Node.js 22以上を要求します。

GraphQL APIとREST APIはどちらを選ぶべきですか？

1画面で参照が深くネストする構成、たとえば記事から著者、著者から所属組織まで辿る画面ではGraphQLが有利で、要求回数を1回に抑えられます。単純な一覧取得や、キャッシュをCDN側で効かせたい配信ではRESTで十分です。公式のJavaScriptクライアント contentful はRESTベースのContent Delivery APIを扱うため、GraphQLを選ぶ場合はクライアント構成が変わる点も見込んでおいてください。