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](references/nextjs-setup.md)
- [Preview and Draft Mode](references/preview-and-draft-mode.md)
- [Troubleshooting](references/troubleshooting.md)