Skip to content
brix.v2.15.0+b120c49

Search documentation

Loading search…

    Documentation menu
    Docs / IntegrationsRead Markdown
    On this page

    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

    #

    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.
    #

    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.