> [Agent navigation index](/llms.txt)

# Contentful

Brix connects Contentful to server-rendered sites and browser-only Contentful Apps without exposing CMS resource shapes throughout an application. Generate model types, read through typed clients, render composed entries through adapters, preview drafts safely, and invalidate delivery caches from verified webhooks.

## Choose a workflow

- [Generate Contentful types](/docs/contentful-typegen.md) — create the deterministic `ContentTypeMap` and use resource types and guards.
- [Use Contentful clients](/docs/contentful-client.md) — configure Delivery, Preview, and Management access; query entries and assets; cache reads; and run incremental sync.
- [Render Contentful entries](/docs/contentful-rendering.md) — isolate CMS fields in adapters and provide visual, Rich Text, and semantic Markdown projections.
- [Enable Contentful Live Preview](/docs/contentful-preview.md) — configure the protected preview route, inspector mode, and safe loader fallbacks.
- [Receive Contentful webhooks](/docs/contentful-webhooks.md) — verify signatures and invalidate native delivery caches after publishing changes.
- [Build Contentful Apps](/docs/contentful-apps.md) — create a managed React App SDK and Forma 36 project, then build and upload it.

## Know which subpath to import

Contentful support is split by where code runs. Browser-safe subpaths can be imported anywhere;
`brix/contentful/server` is a `"use server"` module, so the build rejects it in browser code.

- `brix/contentful` (browser-safe): resource types such as `Entry`, `Asset`, and
  `RichTextDocument`; the guards `isEntry`, `isAsset`, `isLink`, `isDeletedEntry`, and
  `isDeletedAsset`; `resolveLinks`; and the direct API contracts.
- `brix/contentful/server` (server-only): the Delivery/Preview and Management clients, their option
  and result types, `ContentfulEntryNotFoundError`, `ContentfulRequestError`, `ContentfulSyncError`,
  webhook verification, and the `createContentfulPreviewIntegration` and
  `createContentfulClientLoadingIntegration` server integrations with `getContentfulLoadingContext`.
- `brix/contentful/rendering` (Preact server and islands, no server-only code): the adapter
  factory, `propsOf`, the registry and rendering provider, and loader result types. Its components
  are Preact components, so React applications cannot import it.
- `brix/contentful/rendering/registry`: the build-generated `renderEntry` and server-only
  `markdownEntry`.
- `brix/contentful/rendering/markdown`: `projectContentfulRichText` for semantic Rich Text output.
- `brix/contentful/app`: the Contentful App SDK `init`, `locations`, and SDK types for managed
  React apps. Forma 36 comes from `@brix/react/contentful` and `@brix/react/contentful/icons`.

## Recommended site setup

Use a CMA token only while generating types. At runtime, create a request-derived Delivery client with a CDA token and a shared server data cache. Keep Preview credentials in server configuration, and register every cached Delivery client that a signed webhook should invalidate.

Contentful entries can travel through page props and islands, but conventional `*.adapter.ts` and `*.adapter.tsx` modules own access to `fields` and `sys`; `brix check` rejects entry-field access elsewhere. The check uses the type of the whole observed value, so it also covers indexed, called, and awaited values (`items[0]!.fields`, `getPage().fields`), destructuring in variables, parameters, `for...of` loops, and assignments, and object or JSX spreads. It runs when application source imports `brix/contentful` or a subpath, or when the application depends on a package built on Brix. Ordinary components receive application props instead. This keeps the content model at the integration boundary and lets the same adapter provide visual rendering, Live Preview behavior, and agent-readable Markdown.

The installed package ships a copyable Contentful-backed SSR recipe at
`node_modules/brix/docs/examples/contentful-site`. It shows these pieces together: an environment
schema, a shared DynamoDB data cache, a request-scoped client, and a verified invalidation webhook
with its test. Merge its modules into your application as its README describes.

See [translations](/docs/translations-usage.md#use-contentful-as-a-source) for dictionary-source options
and the current typed-entry boundary limitation, [caching](/docs/caching.md) for shared stores and cache
policy, [results](/docs/results.md) for expected client failures, and [environment](/docs/environment.md)
for secrets.
