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 — create the deterministic
ContentTypeMapand use resource types and guards. - Use Contentful clients — configure Delivery, Preview, and Management access; query entries and assets; cache reads; and run incremental sync.
- Render Contentful entries — isolate CMS fields in adapters and provide visual, Rich Text, and semantic Markdown projections.
- Enable Contentful Live Preview — configure the protected preview route, inspector mode, and safe loader fallbacks.
- Receive Contentful webhooks — verify signatures and invalidate native delivery caches after publishing changes.
- Build Contentful Apps — 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 asEntry,Asset, andRichTextDocument; the guardsisEntry,isAsset,isLink,isDeletedEntry, andisDeletedAsset;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 thecreateContentfulPreviewIntegrationandcreateContentfulClientLoadingIntegrationserver integrations withgetContentfulLoadingContext.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-generatedrenderEntryand server-onlymarkdownEntry.brix/contentful/rendering/markdown:projectContentfulRichTextfor semantic Rich Text output.brix/contentful/app: the Contentful App SDKinit,locations, and SDK types for managed React apps. Forma 36 comes from@brix/react/contentfuland@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 for dictionary-source options and the current typed-entry boundary limitation, caching for shared stores and cache policy, results for expected client failures, and environment for secrets.