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

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

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

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

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

```

To upload another built directory, pass `--bundle-dir` once:

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