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.

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.

Not in scope

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

Contentful MCP note

• 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.

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

Workflow

1. Check the latest stable Next.js release online at https://github.com/vercel/next.js/releases when version-specific guidance is needed.
2. Confirm Next.js project structure (App Router vs Pages Router).
3. 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.
4. Install and initialize contentful SDK.
5. Implement published-content fetching.
6. Add preview-aware behavior for Draft Mode.
7. Validate with a minimal test route/page and troubleshooting checklist.

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.

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

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.

References

• Next.js setup
• Preview and Draft Mode
• Troubleshooting