microcms-nextjs

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

microCMS + Next.js

Next.jsプロジェクトでmicroCMSを適切に利用できるよう、既存コード・Next.jsのバージョン・キャッシュ構成を確認しながら具体的な実装まで支援する。

原則として日本語で回答する。ユーザーが別の言語を指定した場合は、その指定に従う。

In Next.js projects, support specific implementation while checking existing code, Next.js version, and cache configuration so that microCMS can be used properly.

As a rule, respond in Japanese. If the user specifies a different language, follow that specification.

基本方針

Basic Policy

既存プロジェクトが利用可能なら、コードを生成する前に構成を確認する。
Next.jsのバージョン、App Router / Pages Router、
```
cacheComponents
```
の有無を確認する。
ユーザーが求める更新反映時間、静的生成の必要性、プレビュー要件を確認する。
microCMS共通の詳細は、
```
microcms-guide
```
が利用可能なら関連リファレンスのみを読む。未導入・未読でも、このSkill内の説明と各リファレンスの公式情報から作業を進める。別Skillの自動読み込みを前提にしない。
新規の例ではApp Routerを基本とするが、既存プロジェクトがPages Routerなら無理に移行させない。
APIキーはサーバー側で扱い、書き込み・下書き全取得・非公開データへアクセスできるキーをブラウザへ渡さない。CSRで直接取得する要件がある場合のみ、公開可能なAPIへのGET専用キーを検討する。Draft Keyも秘密情報として扱う。
Next.jsのキャッシュ仕様はバージョン依存性が高いため、古いパターンを機械的に適用しない。

If an existing project is available, check its configuration before generating code.
Check the Next.js version, App Router / Pages Router, and whether
```
cacheComponents
```
is set.
Check the update propagation time required by the user, the need for static generation, and preview requirements.
For common microCMS details, if
```
microcms-guide
```
is available, read only the relevant references. Even if not introduced or read, proceed with the explanations in this Skill and the official information in each reference. Do not assume automatic loading of another Skill.
For new examples, App Router is the base, but if an existing project uses Pages Router, do not force migration.
Keep API keys on the server side, and do not pass keys that can write, fetch all drafts, or access unpublished data to the browser. Only if there is a requirement to fetch directly from the client (CSR), consider a GET-only key for a public API. Treat the Draft Key as secret information.
Next.js cache specifications are highly version-dependent; do not mechanically apply old patterns.

最初にプロジェクト状態を判定する

Determine the Project State First

キャッシュ・データ取得・Draft Modeに関する作業では、可能なら次を先に確認する。

```
package.json
```
の
```
next
```
バージョン
```
app/
```
または
```
src/app/
```
の有無
```
pages/
```
または
```
src/pages/
```
の有無
```
next.config.*
```
の
```
cacheComponents
```
設定
```
microcms-js-sdk
```
のバージョン
microCMSクライアントの作成場所
APIキーの環境変数名
ホスティング先と実行Runtime
```
output: 'export'
```
の有無（静的エクスポートではサーバー上のISR・Draft Mode・Webhook受信は実行できない）

既存の

revalidate

、

revalidatePath

、

revalidateTag

、

use cache

、

cacheLife

、

cacheTag

の利用状況

これらをコードから確認できる場合、ユーザーへ同じ情報を質問しない。

For work related to caching, data fetching, and Draft Mode, check the following first when possible:

```
next
```
version in
```
package.json
```
Existence of
```
app/
```
or
```
src/app/
```
Existence of
```
pages/
```
or
```
src/pages/
```
```
cacheComponents
```
setting in
```
next.config.*
```
```
microcms-js-sdk
```
version
Where the microCMS client is created
Environment variable names for API keys
Hosting destination and runtime
Whether
```
output: 'export'
```
is used (static export cannot run ISR, Draft Mode, or Webhook reception on the server)

Current usage of

revalidate

revalidatePath

revalidateTag

use cache

cacheLife

cacheTag

If these can be confirmed from the code, do not ask the user the same information.

Next.js 16以降のキャッシュモデルを区別する

Distinguish the Cache Model of Next.js 16 and Later

Next.js 16では

cacheComponents: true

を有効にした場合と、従来のキャッシュモデルで設計が異なる。

cacheComponents: true

の場合は

use cache

、

cacheLife

、

cacheTag

を中心に考える。

```
cacheComponents
```
を利用していない場合は、
```
fetch
```
の
```
cache
```
/
```
next.revalidate
```
、Route Segment Config、
```
revalidatePath
```
/
```
revalidateTag
```
など従来モデルを確認する。

export const revalidate = 60

をすべてのNext.jsプロジェクトへ無条件に提案しない。

詳細は references/caching.md を読む。

In Next.js 16, the design differs when

cacheComponents: true

is enabled versus the traditional cache model.

When

cacheComponents: true

, think primarily in terms of

use cache

cacheLife

, and

cacheTag

When
```
cacheComponents
```
is not used, check the traditional model such as
```
fetch
```
```
cache
```
/
```
next.revalidate
```
, Route Segment Config, and
```
revalidatePath
```
/
```
revalidateTag
```
.

Do not unconditionally propose

export const revalidate = 60

for every Next.js project.

Read references/caching.md for details.

Server Componentsを基本にする

Make Server Components the Default

App RouterでmicroCMSの公開データをページ表示に使う場合は、特別な理由がなければServer Componentからサーバー側で取得する方法を第一候補にする。

以下の理由だけでClient Componentへしない。

microCMSを使っているから
API取得があるから
ページ内に一部インタラクションがあるから

クライアント側の状態・イベント・ブラウザAPIが必要な部分だけをClient Componentへ分離する。

Server Componentから自分自身のRoute Handlerを経由してmicroCMSへアクセスする二重構成も、認証・BFF等の具体的理由がなければ作らない。

When using microCMS public data for page display in the App Router, unless there is a special reason, make server-side fetching from Server Components the first candidate.

Do not make it a Client Component for the following reasons alone:

Because microCMS is used
Because there is an API fetch
Because there is some interaction on the page

Separate only the parts that need client-side state, events, or browser APIs into Client Components.

Do not create a double configuration where a Server Component accesses microCMS through its own Route Handler unless there is a specific reason such as authentication or BFF.

必要なリファレンスだけを読み込む

Load Only the Necessary References

セットアップ:
```
microcms-js-sdk
```
、環境変数、クライアント、型、安全な配置については references/setup.md を読む。
データ取得: Server Components、一覧・詳細、Dynamic Routes、
```
generateStaticParams
```
、ページネーション、大量ページのビルド時の429については references/data-fetching.md を読む。
キャッシュ・ISR: Next.js 16のCache Components、従来モデル、ISR、On-demand Revalidation、Webhook、更新反映問題については references/caching.md を読む。
プレビュー: microCMSのDraft KeyとNext.js Draft Mode、プレビュー開始・終了Route Handlerについては references/preview.md を読む。
画像:
```
next/image
```
、
```
remotePatterns
```
、microCMS画像API、custom loaderの使い分けについては references/images.md を読む。

複数領域にまたがる場合は必要なリファレンスを組み合わせる。

例:

「Webhookで記事更新を即反映したい」 →
```
caching.md
```
「下書きプレビューが古い」 →
```
preview.md
```
+
```
caching.md
```
「画像転送量を減らしたい」 →
```
images.md
```
+
```
microcms-guide
```
の画像・performance原則

Setup: Read references/setup.md for
```
microcms-js-sdk
```
, environment variables, client, types, and secure placement.
Data fetching: Read references/data-fetching.md for Server Components, list/detail pages, Dynamic Routes,
```
generateStaticParams
```
, pagination, and 429 errors when building many pages.
Caching / ISR: Read references/caching.md for Next.js 16 Cache Components, the traditional model, ISR, On-demand Revalidation, Webhooks, and update propagation problems.
Preview: Read references/preview.md for microCMS Draft Key, Next.js Draft Mode, and Route Handlers for starting/ending preview.
Images: Read references/images.md for
```
next/image
```
,
```
remotePatterns
```
, microCMS image API, and how to use custom loaders.

For issues spanning multiple areas, combine the necessary references.

Examples:

"I want to reflect article updates immediately with a Webhook" →
```
caching.md
```
"Draft preview is outdated" →
```
preview.md
```
+
```
caching.md
```
"I want to reduce image transfer volume" →
```
images.md
```
+ the image/performance principles in
```
microcms-guide
```

実装を変更するとき

When Changing Implementation

既存プロジェクトでは次の順に進める。

現在のmicroCMSクライアントとデータ取得関数を確認する。
キャッシュ戦略を確認する。
問題を再現する経路を特定する。
最小限の変更で解決する。
プロジェクト既存の命名・ディレクトリ・型・lint/format方針に従う。
不要な依存パッケージや抽象化を追加しない。

ユーザーがコード修正を求めている場合は、説明だけで終わらせず、可能なら実際のファイルへ一貫した変更を行う。

For existing projects, proceed in the following order:

Check the current microCMS client and data fetching functions.
Check the cache strategy.
Identify the path that reproduces the problem.
Solve it with minimal changes.
Follow the project's existing naming, directory, type, and lint/format conventions.
Do not add unnecessary dependencies or abstractions.

If the user asks for code modifications, do not stop at explanation; if possible, make consistent changes to the actual files.

更新が反映されない問題を診断する

Diagnosing When Updates Are Not Reflected

「microCMSでは更新したのにNext.jsへ反映されない」場合は、次の順序で切り分ける。

microCMS Content APIを直接確認し、期待する公開データが返っているか。
Next.jsがどのデータ取得方式を使っているか。
```
cacheComponents
```
の有無とキャッシュ設定。
時間ベースのrevalidationかOn-demand Revalidationか。
Webhookが受信できているか。
```
revalidatePath
```
/
```
revalidateTag
```
/
```
cacheTag
```
の対象が正しいか。
ホスティング・CDNなど別キャッシュ層があるか。

microCMSのCDNとNext.jsのキャッシュを混同しない。

If "I updated microCMS, but it is not reflected in Next.js", isolate the cause in this order:

Directly check the microCMS Content API to see if the expected public data is returned.
Which data fetching method Next.js uses.
Whether
```
cacheComponents
```
exists and its cache settings.
Time-based revalidation or on-demand revalidation.
Whether the Webhook is being received.
Whether
```
revalidatePath
```
/
```
revalidateTag
```
/
```
cacheTag
```
targets are correct.
Whether there is another cache layer such as hosting or CDN.

Do not confuse microCMS's CDN with Next.js's cache.

品質基準

Quality Standards

公式開発者ドキュメントの取得・仕様確認には、利用可能なら

microcms-docs

を併用する。設計判断や実装はこのSkillで進め、必要なページだけ確認する。未導入の場合は各referenceの公式出典を直接確認する。

バージョン依存のNext.js挙動は、可能なら現在の公式Next.jsドキュメントを確認する。
新規コードも導入済みNext.js・SDKのバージョンに合わせる。最新ドキュメントのAPIを旧バージョンへそのまま持ち込まない。同梱内容と対象バージョンの公式仕様が矛盾する場合は公式仕様を優先する。
キャッシュ戦略は更新要件から逆算する。
公開予約など時刻の正確性が重要な場合は、時間ベースISRだけで要件を満たせるか慎重に判断する。
Draft Modeでは秘密情報とリダイレクト先を検証する。
画像最適化では、Next.js Image OptimizationとmicroCMS画像APIの役割を明確にし、二重最適化を目的なく行わない。
microCMS固有の仕様をNext.jsの仕様として、Next.js固有の仕様をmicroCMSの仕様として説明しない。

When obtaining official developer documentation and confirming specifications, use

microcms-docs

if available. Proceed with design decisions and implementation in this Skill, and reference only the necessary pages. If not introduced, directly check the official sources of each reference.

For version-dependent Next.js behavior, check the current official Next.js documentation when possible.
Match new code to the installed Next.js and SDK versions. Do not bring the latest documentation APIs directly into old versions. If the bundled content contradicts the official specification for the target version, prioritize the official specification.
Derive the cache strategy backward from update requirements.
When time accuracy is important, such as scheduled publishing, carefully judge whether time-based ISR alone can satisfy the requirement.
In Draft Mode, validate secret information and redirect destinations.
For image optimization, clarify the roles of Next.js Image Optimization and the microCMS image API, and do not perform double optimization without purpose.
Do not explain microCMS-specific specifications as Next.js specifications, or Next.js-specific specifications as microCMS specifications.