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

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

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.

Distinguish the Cache Model of Next.js 16 and Later

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.

Make Server Components the Default

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

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

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

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

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.

microcms-nextjs

NPX Install

Tags

SKILL.md Content (Chinese)