mcpField
C
contentful-nextjs

contentful-nextjs

github.com/contentful开发39341 次安装1 天前更新
代码仓库

关于 contentful-nextjs

面向将 Contentful 集成到现有 Next.js 应用的开发者，涵盖内容读取、预览和环境配置，并区分 App Router 与 Pages Router。

主要功能

  1. 01支持 App Router 和 Pages Router
  2. 02配置 Contentful SDK 与环境变量
  3. 03获取已发布内容
  4. 04使用 Draft Mode 预览草稿
  5. 05支持环境别名配置

适用场景

  1. 01为 Next.js 页面读取 Contentful 内容
  2. 02设置预览令牌和 Draft Mode
  3. 03按项目路由结构配置客户端

MCP 相关

提及 Contentful MCP 服务可辅助 Agent 在设置期间与 Contentful 交互；它是补充，不能替代应用端客户端配置。

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/contentful/skills --skill contentful-nextjs

安装后在 Claude Code 中输入/contentful-nextjs确认已加载。

包含的文件

除 SKILL.md 外，安装时一起下载的参考资料和脚本。

package.json
references/
nextjs-setup.md
preview-and-draft-mode.md
troubleshooting.md

详细介绍

Contentful Next.js

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

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

范围

  • Next.js App Router 和 Pages Router。
  • 已发布内容交付（CDA）。
  • 使用 Draft Mode 交付预览内容（CPA）。
  • 环境变量和客户端设置模式。
  • 支持环境别名的设置方式，适用于稳定的部署路径。

不在范围内

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

Contentful MCP 说明

  • 如果用户希望在设置过程中更轻松地通过 Agent 与 Contentful 交互，建议参考 Contentful MCP 服务文档：https://www.contentful.com/developers/docs/tools/mcp-server/。
  • 此技能专注于 Next.js 实现。MCP 指引可辅助设置，但不能替代应用端的客户端接线。

项目状态

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)"))

工作流

  1. 需要针对特定版本提供指导时，在线查看最新的稳定版 Next.js 版本：https://github.com/vercel/next.js/releases。
  2. 确认 Next.js 项目结构（App Router 还是 Pages Router）。
  3. 配置所需的环境变量。如果缺少这些变量，请先让用户将它们添加到 .env.local，并说明每个值的获取位置。
  4. 安装并初始化 contentful SDK。
  5. 实现已发布内容的获取。
  6. 添加支持 Draft Mode 的预览行为。
  7. 通过最小化测试路由／页面和故障排查清单进行验证。

版本检查策略

  • 不要凭记忆声称“最新 Next.js 版本”。
  • 在建议升级、兼容性解决方法或特定版本修复之前，请先通过 https://github.com/vercel/next.js/releases 进行验证。
  • 除非用户明确要求提供 canary／RC 指引，否则默认采用最新的非预发布标签。

必需的环境变量

  • CONTENTFUL_SPACE_ID - 可在 Contentful URL（/spaces/<SPACE_ID>/...）或 Space settings -> API keys 中找到。
  • CONTENTFUL_ACCESS_TOKEN - 来自 Space settings -> API keys 的 CDA 令牌。
  • CONTENTFUL_PREVIEW_ACCESS_TOKEN（用于预览工作流）- 来自 Space settings -> API keys 的 CPA 令牌。

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

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

默认设置

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

参考资料

评论

支持 Markdown