Contentful SDK Guide

Comprehensive guide for Contentful SDKs in TypeScript/JavaScript.

Which SDK Do You Need?

• Management SDK (CMA): Creating/updating content, managing content types, assets, environments → Start at references/management/overview.md
• Delivery SDK (CDA): Fetching published content for production apps → Start at references/delivery/overview.md
• App Framework: Building Contentful Apps that extend the UI → Start at references/app-framework/overview.md

Management SDK (CMA)

For creating, updating, and managing content, content types, assets, and environments.

Start here: references/management/overview.md

Topics:

• **content-types.md** - Define and update content models with field types and validations
• **entries.md** - Create, update, query, and publish entries with version locking
• **assets.md** - Upload, process, and publish media files
• **environments.md** - Create, clone, and manage environments and aliases
• **error-handling.md** - Handle rate limits, version conflicts, and validation errors
• **bulk-operations.md** - Pagination, batch processing, and concurrency control

Delivery SDK (CDA)

For fetching published content in production applications.

Start here: references/delivery/overview.md

Topics:

• **querying.md** - Query parameters, filters, search operators, and pagination
• **includes-links.md** - Link resolution, includes parameter, and handling references
• **localization.md** - Locale handling, fallbacks, and multi-language content
• **rich-text.md** - Rendering rich text fields with embedded entries and assets

App Framework SDK

For building apps that extend the Contentful UI.

Start here: references/app-framework/overview.md

Topics:

• **locations.md** - All app locations: field, sidebar, dialog, entry editor, page, config
• **sdk-apis.md** - Navigator, dialogs, notifier, access, and window APIs
• **parameters.md** - Installation, instance, and invocation parameters

Quick Reference

Version Locking (Management SDK)

Always pass sys when updating to prevent conflicts:

const entry = await client.entry.get({ spaceId, environmentId, entryId })
await client.entry.update({ spaceId, environmentId, entryId }, {
  sys: entry.sys,  // Required for version locking
  fields: { ... }
})

TypeScript Entry Skeletons (Delivery SDK)

Define type-safe content structures:

type BlogPostSkeleton = {
  contentTypeId: 'blogPost'
  fields: {
    title: EntryFieldTypes.Text
    slug: EntryFieldTypes.Symbol
    body: EntryFieldTypes.RichText
  }
}
const entry = await client.getEntry<BlogPostSkeleton>('entry-id')

CMA Integration in Apps (App Framework)

Use SDK adapter to avoid exposing tokens:

import contentful from 'contentful-management'

const cma = contentful.createClient(
  { apiAdapter: sdk.cmaAdapter },
  {
    type: 'plain',
    defaults: {
      spaceId: sdk.ids.space,
      environmentId: sdk.ids.environmentAlias ?? sdk.ids.environment
    }
  }
)