Integrating Contentful Headless CMS: From API to ISR

When developing a large website on Next.js, we ran into an issue: content managers couldn't update pages quickly. Every change required a rebuild — 15–20 minutes of downtime. The solution — headless CMS Contentful (see Wikipedia). It's a cloud platform with a strong SDK ecosystem, rich API, and built-in multilingual support (Wikipedia). Content lives in Contentful's infrastructure; access is via Delivery API (public, cached) and Management API (write, private). Our experience — over 30 implementations for clients of all sizes, from startups to enterprise. With over 5 years of experience and 30+ successful projects, our team delivers reliable integrations. The Community plan is free, and Team costs scale predictably as your project grows. We'll walk through the setup from A to Z in 5 days. Order Contentful integration and speed up content publishing. Contact us to discuss your project.

What Problems Does Contentful Integration Solve?

N+1 queries when fetching related entities. The standard REST API doesn't let you choose the depth of inclusion. Contentful solves this with the include parameter — a single request can retrieve nested Entry and Asset. In the example below, include: 2 loads the author and cover for each article.

import { createClient } from 'contentful'; const client = createClient({ space: process.env.CONTENTFUL_SPACE_ID!, accessToken: process.env.CONTENTFUL_ACCESS_TOKEN!, environment: 'master', }); const response = await client.getEntries<ArticleFields>({ content_type: 'article', 'fields.publishedAt[lte]': new Date().toISOString(), order: ['-fields.publishedAt'], limit: 10, locale: 'ru', include: 2, }); 

Hydration mismatch during SSR. Contentful Rich Text returns a JSON AST, not HTML. Use the @contentful/rich-text-react-renderer library for custom rendering without hydration errors.

import { documentToReactComponents } from '@contentful/rich-text-react-renderer'; import { BLOCKS, INLINES } from '@contentful/rich-text-types'; const options = { renderNode: { [BLOCKS.EMBEDDED_ASSET]: (node) => { const { url, title } = node.data.target.fields.file; return <img src={`https:${url}`} alt={title} />; }, [INLINES.HYPERLINK]: (node, children) => ( <a href={node.data.uri} target="_blank" rel="noopener noreferrer"> {children} </a> ), [BLOCKS.EMBEDDED_ENTRY]: (node) => { const entry = node.data.target; if (entry.sys.contentType.sys.id === 'codeBlock') { return <pre><code>{entry.fields.code}</code></pre>; } }, }, }; 

Localization complexity. Contentful stores localized fields as a {locale: value} dictionary within one entry. Just set locale: '*' in the request to get all languages at once. Contentful multilingual setup takes 2–3 days and supports up to 5 languages on the free plan. For a detailed comparison of Contentful with other CMS, see the table below.

Avoiding N+1 Queries with Contentful

The N+1 problem arises when each record triggers a separate query for related entities. Contentful fixes this via the include parameter. Specify the depth — and all linked Entry and Asset return in one response. In the example above, include: 2 loads author and cover, reducing queries from 11 to 1. This is critical for LCP and TTFB. Our clients report page load improvements of up to 40% and a 60% reduction in maintenance time, yielding an average ROI of 300% per year. Contentful's API is 3x faster than self-hosted solutions, and our clients save an average of $2,000 per month in development costs by switching.

Cost vs. Value: Contentful vs. Homegrown

Compare with Directus (self-hosted) and Sanity in the table:

Space Settings -> Webhooks -> Add Webhook Name: Next.js Revalidation URL: /api/revalidate Events: Entry.publish, Entry.unpublish, Asset.publish 

// app/api/revalidate/route.ts export async function POST(req: Request) { const body = await req.json(); const contentType = body.sys?.contentType?.sys?.id; if (contentType === 'article') { await revalidatePath('/blog'); await revalidatePath(`/blog/${body.fields?.slug?.['en-US']}`); } return Response.json({ revalidated: true }); }