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:

import { useState } from "@brix/react";
import { createRoot } from "@brix/react/client";
import { Button, GlobalStyles } from "@brix/react/contentful";
import { PlusIcon } from "@brix/react/contentful/icons";
import { init, locations, type KnownAppSDK } from "brix/contentful/app";

brix/contentful/app also exports SDK types for configuration, dialogs, editors, fields, home, pages, and sidebars. Initialize the SDK before rendering:

init((sdk) => root.render(<ContentfulApp sdk={sdk} />));

Inside the app, use sdk.location.is(locations.LOCATION_APP_CONFIG) and the other location constants to render the appropriate surface. Configuration screens should register sdk.app.onConfigure(...) and call sdk.app.setReady() when ready. 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

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:

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. Keep credentials in your environment or the authentication flow supported by App Scripts, not in source control.