#001

Install CDA SDK

Use the official SDK — handles auth, retries, normalisation, and TypeScript types automatically.

Setup & Init

#002

Initialise CDA client

Store credentials in env vars — never hardcode tokens in source code.

Setup & Init

#003

Initialise CMA client

CMA token has write access — never expose it in client-side code.

Setup & Init

#004

Preview API client

Preview API returns unpublished entries — use only server-side, never in client bundles.

Setup & Init

#005

Multiple environments

Use staging/dev environments for schema changes — never test migrations on master.

Setup & Init

#006

Retry & timeout config

The SDK retries rate-limited (429) requests automatically. Set a generous timeout for slow networks.

Setup & Init

#007

.env variables

Keep all four tokens: CDA, Preview, CMA, and Space ID. Validate them at startup.

Setup & Init

#008

Validate env at startup

Fail loudly at startup — better than a cryptic runtime error deep in a request.

Setup & Init

#009

Client singleton pattern

Create the client once and reuse — avoids creating multiple HTTP connection pools.

Setup & Init

#010

Select client by mode

Pass a single helper to data fetchers — they get the right client (preview vs live) automatically.

Setup & Init

#011

Custom fetch adapter

Override the adapter to add global logging, custom headers, or mock responses in tests.

Setup & Init

#012

SDK response format

Every entry has sys (metadata) and fields (your content). Always access fields for content.

Setup & Init

#013

SDK version & changelog

Pin the SDK version in production. Check the changelog before major upgrades — breaking changes happen.

Setup & Init

#014

Content type IDs

Content type IDs are set when you create the type — they cannot be changed later. Use camelCase.

Setup & Init

#015

Get single entry

Always destructure fields — raw entries also carry sys and metadata you usually don't need to render.

Content Delivery API

#016

Get entries by content type

Always pass content_type — omitting it scans every type in your space (much slower).

Content Delivery API

#017

Pagination

Max limit is 1000 per request. Use skip+limit loops for full collection fetches.

Content Delivery API

#018

Select specific fields

Always use select in list views — removing 10 fields from 1000 entries = massive payload reduction.

Content Delivery API

#019

Include linked entries

include depth resolves linked entries inline. Default is 1, max is 10. Deeper = larger payload.

Content Delivery API

#020

Order results

Prefix with - for descending. sys.createdAt is the most reliable for chronological ordering.

Content Delivery API

#021

Get asset

Asset URLs have no protocol — always prepend https: before using in img src.

Content Delivery API

#022

Get all assets

Filter by contentType to retrieve only images, videos, PDFs, etc.

Content Delivery API

#023

withAllLocales flag

Returns all locales in one call — fields become objects keyed by locale code.

Content Delivery API

#024

withoutUnresolvableLinks

Strips broken links silently instead of throwing — safer when linked entries may be unpublished.

Content Delivery API

#025

Stop reason / stop_reason

Check stop_reason to detect if a response was paginated or complete.

Content Delivery API

#026

Sync API — initial

Sync API gives you a token. Store it to enable incremental syncs and avoid full rebuilds.

Content Delivery API

#027

Sync API — incremental

Only fetches entries changed since the last sync — drastically cuts build times on large spaces.

Content Delivery API

#028

Count-only query

Use limit: 0 to get total count without fetching any entry data — very cheap.

Content Delivery API

#029

Locale parameter

Always pass locale explicitly — relying on defaults causes subtle locale mismatch bugs.

Content Delivery API

#030

Entries by IDs (bulk)

Fetch multiple known IDs in one request — avoids N+1 patterns.

Content Delivery API

#031

Chaining query helpers

Build typed helpers for common queries — reduces duplication and makes fetchers readable.

Content Delivery API

#032

Throttle polling

Never poll CDA on every request — use cache + webhooks + ISR instead.

Content Delivery API

#033

Locale fallback chain

Contentful respects locale fallback chains you configure in the dashboard — SDK honours them automatically.

Content Delivery API

#034

Detect archived entries

Archived entries still exist on CDA with sys.archivedAt set — exclude them explicitly.

Content Delivery API

#035

Create entry

Fields must match your content type schema exactly — extra fields are rejected.

Content Management API

#036

Publish entry

Entries must be published to appear via CDA. Draft = invisible to public.

Content Management API

#037

Unpublish entry

Unpublished entries remain in Contentful but are hidden from CDA.

Content Management API

#038

Update entry fields

Always re-fetch before updating to get the latest sys.version — avoids 409 version conflicts.

Content Management API

#039

Delete entry

You cannot delete a published entry — unpublish first or you get a 422 error.

Content Management API

#040

Upload asset

Two-step process: create asset metadata, then call processForAllLocales() to trigger the upload.

Content Management API

#041

Link entry to another

Links use sys.type Link + linkType — never store raw IDs in reference fields.

Content Management API

#042

Bulk publish

Use the bulk actions API for 200+ items — single-publish loops hit rate limits fast.

Content Management API

#043

Bulk unpublish

Bulk unpublish is much faster than looping unpublish() calls one by one.

Content Management API

#044

Scheduled publishing

Use Scheduled Actions to publish/unpublish entries at a specific future time.

Content Management API

#045

Read version history

Snapshots preserve full entry state — useful for audit trails and manual rollback.

Content Management API

#046

Content type CRUD

Always call update() then publish() after editing a content type definition.

Content Management API

#047

Patch entry (REST)

The SDK has no PATCH — use the CMA REST endpoint with JSON Patch for partial updates.

Content Management API

#048

Tag management

Metadata tags are space-level — create once, reuse across all entry types.

Content Management API

#049

Editorial tasks

Tasks are Contentful's built-in workflow mechanism — assign review tasks to team members.

Content Management API

#050

Search & replace via CMA

Bulk update field values across all entries — useful for domain changes or copy updates.

Content Management API

#051

GraphQL endpoint

Use GraphQL when you need precise field selection across nested types — avoids over-fetching.

GraphQL API

#052

Basic collection query

Collection queries return items array + total. Always request sys.id for React key props.

GraphQL API

#053

Query with variables

Always use variables — never string-interpolate user input into GraphQL queries.

GraphQL API

#054

Nested linked entries

GraphQL lets you define exact nested fields — no more guessing include depth.

GraphQL API

#055

Preview via GraphQL

Add preview: true to query unpublished draft entries from GraphQL.

GraphQL API

#056

Where filter syntax

GraphQL filters are strongly typed — they map 1:1 with CDA operators.

GraphQL API

#057

__typename for polymorphism

Use __typename to switch renderer components for union-type sections fields.

GraphQL API

#058

Fragments

Use fragments to share field selections across queries — keeps queries DRY.

GraphQL API

#059

Pagination in GraphQL

Contentful GraphQL uses skip+limit pagination — not cursor-based.

GraphQL API

#060

sys fields in GraphQL

sys.id, publishedAt, and firstPublishedAt are frequently needed — always include sys.

GraphQL API

#061

Apollo Client setup

Apollo's normalised cache + automatic refetching pairs well with Contentful GraphQL.

GraphQL API

#062

Asset collection query

Query assets via GraphQL for fully typed access to file metadata and dimensions.

GraphQL API

#063

GraphQL playground

Use the interactive playground to explore your schema and build queries before adding them to code.

GraphQL API

#064

Persisted queries

Persist frequently-used queries server-side to reduce bandwidth and enable CDN caching.

GraphQL API

#065

Install renderer

Never parse rich text JSON manually — always use the official renderer.

Rich Text

#066

Basic render

documentToReactComponents handles all standard node types out of the box.

Rich Text

#067

Custom node renderers

Always define custom renderers for embedded entries and assets — defaults are bare wrappers.

Rich Text

#068

Embedded asset renderer

Always add width + height to avoid layout shift — both are in file.details.image.

Rich Text

#069

Custom marks

Custom mark renderers let you apply your design system's typography to bold/italic/code.

Rich Text

#070

Rich text in GraphQL

GraphQL returns rich text as { json, links }. Pass links to your renderer for embedded entry resolution.

Rich Text

#071

Resolve embedded from GraphQL

Build a lookup map from links.entries.block for O(1) resolution in custom renderers.

Rich Text

#072

Plain text extract

Use the plain text renderer for meta descriptions, OG tags, and word counts.

Rich Text

#073

Tables in rich text

Rich text tables are supported since 2022 — requires @contentful/rich-text-types ≥14.

Rich Text

#074

Table of contents generator

Walk rich text JSON to extract headings — no DOM parsing needed.

Rich Text

#075

Anchor links from headings

Generate anchor IDs from heading text for table-of-contents deep linking.

Rich Text

#076

Code blocks with syntax highlight

Wrap code blocks in a custom renderer with react-syntax-highlighter.

Rich Text

#077

Footnotes via embedded entries

Use an embedded inline entry type 'Footnote' to store footnote text inline.

Rich Text

#078

Rich text to HTML string

Use the HTML renderer for email templates, RSS feeds, and server-side rendering without React.

Rich Text

#079

Image transformation API

Contentful Images API resizes/crops/converts on-the-fly — no separate CDN needed.

Assets & Media

#080

Responsive srcset

Build srcsets from a single Contentful URL — no extra storage or image duplication.

Assets & Media

#081

Next/Image with Contentful

Use a custom loader to combine Next.js image optimisation with Contentful transforms.

Assets & Media

#082

AVIF / WebP negotiation

AVIF is 30-50% smaller than WebP at the same quality — use picture for progressive enhancement.

Assets & Media

#083

Focal-point crop

Use f= to control crop focal point — face detection finds faces automatically.

Assets & Media

#084

Blur placeholder

Generate a tiny base64 placeholder for images before they load — eliminates layout shift.

Assets & Media

#085

Video assets

Contentful stores but doesn't transcode video. Use Mux or Cloudinary for HLS streaming.

Assets & Media

#086

Audio assets

HTML5 audio element works directly with Contentful audio file URLs.

Assets & Media

#087

PDF & file assets

Detect content type before rendering — PDFs and binaries need download links, not img tags.

Assets & Media

#088

Lazy load images

Use loading=lazy on below-fold images — no JS required, supported in all modern browsers.

Assets & Media

#089

SVG assets

Use img tag for SVGs from Contentful — dangerouslySetInnerHTML risks XSS.

Assets & Media

#090

Dominant color placeholder

Store dominant color on your asset entry for a branded loading state.

Assets & Media

#091

Equality filter

Fields must be marked as searchable in your content type for filtering to work.

Querying & Filtering

#092

String operators

[match] is full-text contains. [in] is exact multi-value OR. [ne] is not-equal.

Querying & Filtering

#093

Range filters

Works on dates, numbers, and any comparable field type.

Querying & Filtering

#094

Array / tags filter

[all] = must contain all values. [in] = must contain at least one.

Querying & Filtering

#095

Location / geo filter

Set field type to Location in Contentful to enable proximity and bounding-box queries.

Querying & Filtering

#096

sys filters

Filter on system metadata — useful for changed-since queries in incremental builds.

Querying & Filtering

#097

Full-text search

query does a full-text search across all searchable fields — always scope with content_type.

Querying & Filtering

#098

Exists / not-exists

[exists] true finds entries where the field is set; false finds where it is missing.

Querying & Filtering

#099

Boolean filtering

Boolean fields: pass true/false as values, not strings — strings return no results.

Querying & Filtering

#100

Filter by linked entry field

Two-level linked filtering: posts where author.country = 'AU'.

Querying & Filtering

#101

AND / OR query patterns

Multiple params are AND'd. For OR, use [in] operator or make separate requests.

Querying & Filtering

#102

Near-real-time content

Cache for 10-30s at edge for near-real-time content without rate limit risk.

Querying & Filtering

#103

Scheduled / future content

Query entries with a future startDate to surface 'coming soon' content.

Querying & Filtering

#104

Complex nested filter

Combine multiple filter levels for powerful content-graph traversal.

Querying & Filtering

#105

Locale parameter

Always pass locale explicitly — relying on defaults causes subtle bugs.

Localization

#106

withAllLocales

withAllLocales avoids N requests for N locales — perfect for static site generation.

Localization

#107

Build paths for all locales

Combine withAllLocales + getStaticPaths for full multilingual SSG with one query.

Localization

#108

Locale fallback chain

Configure fallbacks in Contentful dashboard — SDK respects them automatically.

Localization

#109

Missing translations audit

Run this before launch — empty locale fields silently show nothing to users.

Localization

#110

RTL locale handling

Detect RTL locales and set dir attribute — Contentful stores content, your app handles direction.

Localization

#111

hreflang tags for SEO

hreflang tags are critical for international SEO — add them for all localised page variants.

Localization

#112

Locale in GraphQL

GraphQL locale filter is per-query — no global default like the SDK client.

Localization

#113

Locale detection middleware

Detect and redirect to user's locale at the edge — no client-side flash.

Localization

#114

Pluralisation with i18n

Use i18next or react-intl for pluralisation rules — Contentful just stores the string.

Localization

#115

Receive webhook (Next.js)

Always verify the webhook secret header — webhooks hit public URLs.

Webhooks

#116

Revalidate on publish

ISR tag revalidation is the most efficient response to a publish webhook.

Webhooks

#117

Webhook event types

Filter webhooks in Contentful to only the events you need — reduces noise.

Webhooks

#118

HMAC webhook verification

Verify HMAC signatures to ensure webhooks are genuinely from Contentful.

Webhooks

#119

Idempotent webhook handler

Contentful retries failed webhooks — make your handler idempotent to avoid duplicate processing.

Webhooks

#120

Queue webhooks with BullMQ

Use a job queue for reliable webhook processing — gives you retries and observability.

Webhooks

#121

Trigger Vercel deploy

Redeploy static sites when content changes using Vercel Deploy Hooks.

Webhooks

#122

Slack notification on publish

Alert editors in Slack when content is published — no extra tools needed.

Webhooks

#123

Audit log via webhooks

Stream all CMS changes to a database for a full editorial audit trail.

Webhooks

#124

Preview webhook on autosave

Trigger preview builds on autosave so editors see live updates without publishing.

Webhooks

#125

App Router fetch with tags

Tag fetch calls so webhooks can trigger granular on-demand revalidation.

Next.js Integration

#126

getStaticProps (Pages Router)

Pass revalidate for ISR — don't build everything at deploy time for large sites.

Next.js Integration

#127

Draft Mode / Preview

Combine Next.js Draft Mode with Contentful Preview API for live content previews.

Next.js Integration

#128

generateStaticParams

Only fetch slug fields — makes param generation fast even for thousands of entries.

Next.js Integration

#129

Metadata API

Generate dynamic OG tags from Contentful SEO fields for every page.

Next.js Integration

#130

Sitemap generation

Generate sitemap.xml at build time from Contentful for full SEO coverage.

Next.js Integration

#131

Streaming with Suspense

Wrap Contentful fetches in Suspense boundaries for streaming SSR.

Next.js Integration

#132

ISR — revalidate segment

ISR is the sweet spot for content sites — static performance + content freshness.

Next.js Integration

#133

Route handler as CMS proxy

Proxy all Contentful requests via your own API — never expose CDA tokens to the client.

Next.js Integration

#134

useContentful SWR hook

SWR + a client-side hook is great for search, filters, and dynamic user interactions.

Next.js Integration

#135

unstable_cache wrapper

Wrap Contentful calls in unstable_cache for cross-request deduplication in the App Router.

Next.js Integration

#136

Parallel data fetching

Promise.all halves load time by fetching independent resources simultaneously.

Next.js Integration

#137

Content-driven navigation

Store nav structure in Contentful — gives marketing teams full menu control.

Next.js Integration

#138

Preview bar component

Show a floating bar in draft mode so editors always know they are in preview.

Next.js Integration

#139

Generate types from model

Use the official generator to avoid manual type drift — run it after schema changes.

TypeScript

#140

Define entry skeleton

Use EntryFieldTypes for field typing — much more precise than any.

TypeScript

#141

Typed getEntries

Pass your skeleton type as a generic to getEntries for fully typed responses.

TypeScript

#142

Content type guard

Type guards prevent runtime errors when handling mixed entry types in dynamic renderers.

TypeScript

#143

Discriminated union sections

Discriminated unions for section/block types give you exhaustive type safety.

TypeScript

#144

Document type for rich text

Use Document from @contentful/rich-text-types for type-safe rich text props.

TypeScript

#145

Asset type helper

A utility function for type-safe asset URL extraction.

TypeScript

#146

Zod validation schema

Validate Contentful responses at runtime with Zod for safety in critical paths.

TypeScript

#147

Infer field types from skeleton

Use TypeScript utility types to extract precise field types.

TypeScript

#148

Mock factory for tests

Type-safe mock factories make unit tests easy and catch schema drift.

TypeScript

#149

Renderer component pattern

A strongly typed map from content type ID to component eliminates switch/if chains.

TypeScript

#150

CMA TypeScript types

Import CMA types for fully typed management operations.

TypeScript

#151

Cache API responses

Contentful responses are stable per publish version — cache aggressively.

Performance & Caching

#152

Redis caching layer

Redis gives sub-millisecond repeat reads — perfect for heavily-trafficked pages.

Performance & Caching

#153

Rate limits

CDA: 55 req/s per space. CMA: 7 req/s. Use exponential backoff on 429s.

Performance & Caching

#154

Edge caching headers

Return Contentful data with s-maxage so Vercel/Cloudflare Edge caches it globally.

Performance & Caching

#155

Request deduplication

Deduplicate identical in-flight requests to avoid multiple identical API calls per render.

Performance & Caching

#156

Avoid over-fetching

Use select to only fetch fields you render — huge payload savings on large entry sets.

Performance & Caching

#157

Bundle tree shaking

Named imports are tree-shakeable — avoids pulling in the full SDK in client bundles.

Performance & Caching

#158

Staggered revalidation

Vary revalidate times to spread cache misses and avoid thundering-herd on ISR.

Performance & Caching

#159

Measure Contentful TTFB

Instrument fetches to track how long Contentful calls take — target <200ms with edge caching.

Performance & Caching

#160

Flatten deep nesting

Flatten your content model if you need include > 3 — deep nesting hurts performance.

Performance & Caching

#161

SWR stale-while-revalidate

SWR shows stale data instantly while refreshing in the background — perfect UX.

Performance & Caching

#162

CDN cache-control headers

Contentful CDA includes s-maxage=300 by default — respect it in your middleware.

Performance & Caching

#163

Reference field patterns

Prefer entry links over duplicating content — single source of truth avoids drift.

Content Modeling

#164

Modular page builder

A 'sections' Array<EntryLink> field enables drag-and-drop page building for editors.

Content Modeling

#165

Taxonomy / tag content type

Use a Tag content type when you need rich tag data like descriptions or colors.

Content Modeling

#166

Global settings singleton

A Settings entry stores site-wide config — query it once and pass via React context.

Content Modeling

#167

Ordered list via integer field

Add a sortOrder: Integer field for editorially-controlled ordering.

Content Modeling

#168

Short text vs long text

Symbol is indexed and filterable. Text is searchable but not filterable. Choose carefully.

Content Modeling

#169

Field validations in CMS

Add validations in the content model — saves client-side validation code.

Content Modeling

#170

Slug auto-generation app

Use the Contentful App Framework to auto-generate slugs from title on entry creation.

Content Modeling

#171

Dynamic forms via CMS

Model form fields in Contentful so marketing teams can build forms without code changes.

Content Modeling

#172

Many-to-many junction entry

Model many-to-many relationships with a junction entry — Contentful has no native M2M.

Content Modeling

#173

Content versioning field

Add a schemaVersion field so query logic can target a specific schema version.

Content Modeling

#174

Slug uniqueness check

Contentful doesn't enforce slug uniqueness — add a CI check or Contentful App.

Content Modeling

#175

Install Contentful CLI

CLI is essential for migrations, environment management, and scripting deployments.

Migrations & CLI

#176

Write a migration script

Never manually edit content models in production — always use migration scripts.

Migrations & CLI

#177

Run migration

Always test on staging first — never run migrations directly on master.

Migrations & CLI

#178

Dry run migration

Run --dry-run to preview changes before applying — no side effects.

Migrations & CLI

#179

Rollback script

Write a companion rollback script for every migration — test it before deploying.

Migrations & CLI

#180

Export / import space

Export a snapshot before major changes — fast rollback if something goes wrong.

Migrations & CLI

#181

Clone environment

Clone to safely test migrations without touching production.

Migrations & CLI

#182

Environment aliases

Point the master alias at a release environment for zero-downtime schema rollouts.

Migrations & CLI

#183

Bulk import via script

Scripted bulk import is faster and auditable vs manual entry creation.

Migrations & CLI

#184

Field reorder migration

Field order in Contentful editor is set via moveField — improves editor experience.

Migrations & CLI

#185

List content types script

Quick audit of your space — useful before starting a migration or onboarding.

Migrations & CLI

#186

CI migration validation

Add migration validation as a CI step — catch schema errors before they reach production.

Migrations & CLI

#187

Never expose tokens client-side

CDA tokens are read-only but still identify your space — proxy via your own API route.

Tips & Tricks

#188

Zero-downtime schema changes

Follow expand/contract: add new field, migrate data, remove old field.

Tips & Tricks

#189

Contentful + Algolia sync

Push entries to Algolia via webhook for blazing-fast search — Contentful is not a search engine.

Tips & Tricks

#190

Content health checks

Run automated checks on entries for SEO, broken links, and missing images.

Tips & Tricks

#191

Mock Contentful in tests

Mock the client to avoid network calls — fast, deterministic, and works offline.

Tips & Tricks

#192

Track changes in git

Export space content to JSON and commit — full history + PR review for content changes.

Tips & Tricks

#193

Contentful Apps SDK

Build custom field editors, sidebar widgets, and page extensions with the App Framework.

Tips & Tricks

#194

Circular reference detection

Circular links crash include resolution — detect and break them in your data layer.

Tips & Tricks

#195

Contentful Compose app

Use the Compose app for page-level content ordering — it's the official page builder UI.

Tips & Tricks

#196

Contentful + TypeSense search

TypeSense is open-source alternative to Algolia — sync Contentful via webhook.

Tips & Tricks

#197

Structured clone before mutation

Deep-clone entries before transforming — avoids mutating cached references.

Tips & Tricks

#198

Space template bootstrap

Bootstrap new client spaces from a template export — perfect for multi-tenant setups.

Tips & Tricks

#199

Content diff for PRs

Show editors a diff of what changed in entries before a PR merges.

Tips & Tricks

#200

Key docs & resources

Bookmark these — the official docs cover edge cases that cost hours to debug.

Tips & Tricks