> [Agent navigation index](/llms.txt)

# 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

```sh
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:

```ts
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`

```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`

```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:

```sh
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:

```sh
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>`:

```sh
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.
