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'sinitandlocations, plus theKnownAppSDK,ConfigAppSDK,DialogAppSDK,EditorAppSDK,FieldAppSDK,HomeAppSDK,PageAppSDK, andSidebarAppSDKtypes.@brix/react/contentfuland@brix/react/contentful/icons— Forma 36 components and icons.@brix/reactand@brix/react/client— React hooks,StrictMode, andcreateRoot.
The generated entry initializes the SDK before rendering:
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:
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.