contentful-nextjs

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Contentful Next.js

Use this skill to integrate Contentful into an existing Next.js application.

Contentful is a headless, API-first CMS (composable content platform) that lets Next.js apps fetch structured content through delivery and preview APIs.

使用本技能将Contentful集成到现有Next.js应用中。

Contentful是一个无头、API优先的CMS（可组合内容平台），允许Next.js应用通过交付API和预览API获取结构化内容。

Scope

适用范围

Next.js App Router and Pages Router.
Published content delivery (CDA).
Preview content delivery with Draft Mode (CPA).
Environment variable and client setup patterns.
Environment alias-aware setup for stable deployment paths.

Next.js App Router和Pages Router。
已发布内容的交付（CDA）。
结合Draft Mode的预览内容交付（CPA）。
环境变量与客户端设置模式。
支持环境别名的设置，以实现稳定的部署路径。

Not in scope

不适用范围

Personalization/optimization implementations.
Studio Experiences SDK setup.
Full content-model strategy design.

个性化/优化方案的实现。
Studio Experiences SDK的设置。
完整内容模型策略设计。

Contentful MCP note

Contentful MCP说明

If the user wants easier agent-driven interaction with Contentful during setup, suggest the Contentful MCP server docs:
```
https://www.contentful.com/developers/docs/tools/mcp-server/
```
.
Keep this skill focused on Next.js implementation. MCP guidance complements setup but does not replace app-side client wiring.

如果用户希望在设置过程中更便捷地通过Agent与Contentful交互，建议参考Contentful MCP服务器文档：
```
https://www.contentful.com/developers/docs/tools/mcp-server/
```
。
本技能专注于Next.js实现。MCP指导仅作为设置的补充，不能替代应用端的客户端配置。

Project state

项目状态

echo "=== Contentful packages ===" && node -e "try{const p=require('./package.json');const d={...p.dependencies,...p.devDependencies};const c=Object.entries(d).filter(([k])=>k.includes('contentful'));console.log(c.length?c.map(([k,v])=>k+'@'+v).join('\n'):'(Contentful SDK not installed)')}catch{console.log('(no package.json)')}" 2>/dev/null
echo ""
echo "=== Contentful env vars ===" && grep -h CONTENTFUL .env.local .env 2>/dev/null | sed 's/=.*/=<set>/' || echo "(no Contentful env vars found in .env.local or .env)"
echo ""
echo "=== Router type ===" && ([ -d "app" ] && echo "App Router detected (app/ directory exists)" || ([ -d "pages" ] && echo "Pages Router detected (pages/ directory exists)" || echo "(could not detect router type)"))

echo "=== Contentful packages ===" && node -e "try{const p=require('./package.json');const d={...p.dependencies,...p.devDependencies};const c=Object.entries(d).filter(([k])=>k.includes('contentful'));console.log(c.length?c.map(([k,v])=>k+'@'+v).join('\n'):'(Contentful SDK not installed)')}catch{console.log('(no package.json)')}" 2>/dev/null
echo ""
echo "=== Contentful env vars ===" && grep -h CONTENTFUL .env.local .env 2>/dev/null | sed 's/=.*/=<set>/' || echo "(no Contentful env vars found in .env.local or .env)"
echo ""
echo "=== Router type ===" && ([ -d "app" ] && echo "App Router detected (app/ directory exists)" || ([ -d "pages" ] && echo "Pages Router detected (pages/ directory exists)" || echo "(could not detect router type)"))

Workflow

工作流程

Check the latest stable Next.js release online at
```
https://github.com/vercel/next.js/releases
```
when version-specific guidance is needed.
Confirm Next.js project structure (App Router vs Pages Router).
Configure required env vars. If they are missing, ask the user to add them to
```
.env.local
```
before continuing, and explain where to find each value.
Install and initialize
```
contentful
```
SDK.
Implement published-content fetching.
Add preview-aware behavior for Draft Mode.
Validate with a minimal test route/page and troubleshooting checklist.

当需要特定版本的指导时，在线查看Next.js最新稳定版本：
```
https://github.com/vercel/next.js/releases
```
。
确认Next.js项目结构（App Router还是Pages Router）。
配置所需的环境变量。如果缺失，请用户先将其添加到
```
.env.local
```
中，并说明每个值的获取位置。
安装并初始化
```
contentful
```
SDK。
实现已发布内容的获取逻辑。
为Draft Mode添加预览相关行为。
通过最小化测试路由/页面和故障排查清单进行验证。

Version-check policy

版本检查规则

Do not rely on memory for "latest Next.js version" claims.
Verify against
```
https://github.com/vercel/next.js/releases
```
before recommending upgrades, compatibility workarounds, or version-specific fixes.
Treat the latest non-prerelease tag as default unless the user explicitly asks for canary/RC guidance.

不要依赖记忆来声称“最新Next.js版本”。
在推荐升级、兼容性解决方案或特定版本修复之前，务必通过
```
https://github.com/vercel/next.js/releases
```
进行验证。
默认使用最新的非预发布版本标签，除非用户明确要求canary/RC版本的指导。

Required environment variables

所需环境变量

```
CONTENTFUL_SPACE_ID
```
- Find it in the Contentful URL (
```
/spaces/<SPACE_ID>/...
```
) or in Space settings -> API keys.
```
CONTENTFUL_ACCESS_TOKEN
```
- CDA token from Space settings -> API keys.
```
CONTENTFUL_PREVIEW_ACCESS_TOKEN
```
(for preview workflows) - CPA token from Space settings -> API keys.

Creating an API key in Contentful provides both tokens needed here:

CDA token ->
```
CONTENTFUL_ACCESS_TOKEN
```
CPA token ->
```
CONTENTFUL_PREVIEW_ACCESS_TOKEN
```

```
CONTENTFUL_SPACE_ID
```
- 在Contentful URL（
```
/spaces/<SPACE_ID>/...
```
）或Space设置 -> API密钥中查找。
```
CONTENTFUL_ACCESS_TOKEN
```
- 来自Space设置 -> API密钥的CDA令牌。
```
CONTENTFUL_PREVIEW_ACCESS_TOKEN
```
（用于预览工作流）- 来自Space设置 -> API密钥的CPA令牌。

在Contentful中创建API密钥会提供此处所需的两个令牌：

CDA令牌 ->
```
CONTENTFUL_ACCESS_TOKEN
```
CPA令牌 ->
```
CONTENTFUL_PREVIEW_ACCESS_TOKEN
```

Defaults

默认设置

If the user does not specify router type, default to Next.js App Router guidance.
Use CDA host for normal delivery.
Use
```
preview.contentful.com
```
and preview token when Draft Mode is enabled.
Prefer an environment alias (for example
```
master
```
) as the client
```
environment
```
value to decouple runtime clients from release environment IDs.
Keep Contentful client creation in a shared utility module.

如果用户未指定路由类型，默认提供Next.js App Router的指导。
使用CDA主机进行常规内容交付。
启用Draft Mode时，使用
```
preview.contentful.com
```
和预览令牌。
优先使用环境别名（例如
```
master
```
）作为客户端的
```
environment
```
值，以将运行时客户端与发布环境ID解耦。
将Contentful客户端的创建逻辑放在共享工具模块中。

References

参考资料

Next.js setup
Preview and Draft Mode
Troubleshooting

Next.js 配置
预览与Draft Mode
故障排查