Skip to content
brix.v2.15.0+b120c49

Search documentation

Loading search…

    Documentation menu
    Docs / Integrations / ContentfulRead Markdown
    On this page

    Contentful Apps

    Create a browser-only React application with managed versions of the Contentful App SDK, App Scripts, React, and Forma 36, then develop, build, and upload it with Brix.

    Create and run an app

    #
    brix create contentful-app editorial-tools
    cd editorial-tools
    brix dev
    

    At a Brix workspace root, a bare name is created under apps/ and uses the workspace's exact Brix version. The project declares brix.project: "react-application" and brix.integrations.contentful: true.

    This preset is a root React SPA, not a Brix Hono/Preact application. It has no server routes, islands, Panda, start command, or managed Storybook. Its portable build uses a relative asset base:

    import { defineBrixReactConfig } from "@brix/react/vite";
    
    export default defineBrixReactConfig({ vite: { base: "./" } });
    

    Use brix dev for React Fast Refresh and brix build for the optimized dist bundle. Brix does not create the Contentful App Definition or configure its locations: manage those in Contentful, point local locations to the development URL printed by Brix, and configure the deployed frontend after upload or hosting.

    Use the SDK and Forma 36 facades

    #

    Import managed dependencies through Brix rather than adding or importing their packages directly:

    • brix/contentful/app — the App SDK's init and locations, plus the KnownAppSDK, ConfigAppSDK, DialogAppSDK, EditorAppSDK, FieldAppSDK, HomeAppSDK, PageAppSDK, and SidebarAppSDK types.
    • @brix/react/contentful and @brix/react/contentful/icons — Forma 36 components and icons.
    • @brix/react and @brix/react/client — React hooks, StrictMode, and createRoot.

    The generated entry initializes the SDK before rendering:

    src/main.tsx
    import { StrictMode } from "@brix/react";
    import { createRoot } from "@brix/react/client";
    import { init } from "brix/contentful/app";
    import { ContentfulApp } from "./App.tsx";
    
    const element = document.getElementById("root");
    if (!element) throw new Error("Contentful app root is missing");
    const root = createRoot(element);
    
    init((sdk) =>
      root.render(
        <StrictMode>
          <ContentfulApp sdk={sdk} />
        </StrictMode>,
      ),
    );
    

    Open the app through its configured Contentful location to exercise the SDK; a standalone browser tab does not provide the Contentful host connection.

    The generated ContentfulApp narrows the SDK by location with a type guard, then registers the configuration handlers on the app configuration screen:

    src/App.tsx
    import { useEffect } from "@brix/react";
    import { GlobalStyles, Heading } from "@brix/react/contentful";
    import { locations, type ConfigAppSDK, type KnownAppSDK } from "brix/contentful/app";
    
    export function ContentfulApp({ sdk }: { sdk: KnownAppSDK }) {
      return (
        <>
          <GlobalStyles />
          {isConfigScreen(sdk) ? <ConfigScreen sdk={sdk} /> : <Heading>Contentful app ready</Heading>}
        </>
      );
    }
    
    function isConfigScreen(sdk: KnownAppSDK): sdk is ConfigAppSDK {
      return sdk.location.is(locations.LOCATION_APP_CONFIG);
    }
    
    function ConfigScreen({ sdk }: { sdk: ConfigAppSDK }) {
      useEffect(() => {
        sdk.app.onConfigure(async () => ({
          parameters: await sdk.app.getParameters(),
          targetState: await sdk.app.getCurrentState(),
        }));
        void sdk.app.setReady();
      }, [sdk]);
    
      return <Heading>Configure your app</Heading>;
    }
    

    Use the other locations constants the same way for entry fields, sidebars, dialogs, and pages. Run brix upgrade to keep React, the SDK, App Scripts, and Forma 36 aligned; do not replace the preset with create-contentful-app.

    Build and upload

    #

    Build before uploading:

    brix build
    brix contentful upload
    

    Run upload from the Contentful app project: it requires brix.project: "react-application" with brix.integrations.contentful: true, and other projects fail with a usage error. Upload runs managed Contentful App Scripts and uses ./dist by default. Any arguments after upload are forwarded to App Scripts, so use its supported flags when selecting an organization or App Definition:

    brix contentful upload --organization-id <organization-id> --definition-id <app-definition-id>
    

    To upload another built directory, pass --bundle-dir once, as --bundle-dir <dir> or --bundle-dir=<dir>:

    brix contentful upload --bundle-dir dist/production
    

    The bundle directory must be project-relative, remain inside dist (including through symlinks), and contain index.html. Absolute paths, paths outside dist, repeated --bundle-dir flags, and missing builds are rejected before App Scripts runs; a missing index.html reports run brix build before upload. Keep credentials in your environment or the authentication flow supported by App Scripts, not in source control.