C4 Connectors

Storybook

When opening a PR, a version of storybook with the changes is deployed automatically and can be accessed by clicking on the link in the PR.

Design system compatibility mode

Every exported component supports an opt-in mode prop, set via C4ConnectorsContextProvider:

import "@camunda/c4-connectors/index.scss" // existing Carbon styles
import "@camunda/design-system/styles.css" // required only if you use mode="ds"

<C4ConnectorsContextProvider apiBaseUrl={...} organizationId={...} mode="ds">
  <C4InboundConnectorsTable onClick={...} />
</C4ConnectorsContextProvider>

• mode="carbon" (default) — renders with Carbon Design System, unchanged from previous versions.
• mode="ds" — renders with @camunda/design-system. Consumers must additionally import @camunda/design-system/styles.css once at their app root — this library does not import it for you, the same way it doesn't import its own index.scss for you.

A handful of components have no design-system equivalent yet and always render as Carbon, in both modes: the Grid/Column layout in C4Page, Layer and Section in the executable details view, and toast notifications. This library's Storybook has a "Design system" toolbar toggle to preview both modes for any story.

Breaking changes

React 19 required — as of v1.7.0, this library requires React 19 (^19.0.0). React 18 is no longer supported.

Dev

🔧 Preparation

There are a few npm packages only available to Camundis, so you first need to create a personal access token on GitHub. To create this token, follow the steps below:

1. Go to https://github.com/settings/tokens.
2. Click Generate new token.
3. Select at least read:packages.
4. Generate the token.
5. Keep the generated token in a safe place (e.g. the Camunda secrets management) because you will never see it again. Important: Enable SSO to allow the token to access the camunda-cloud artifacts.
6. Add the generated token to your environment. See the example below for Linux: export NPM_TOKEN=ghp_imiJmvG46E6wo7V4ANwurstbrotXafCg
7. Next, run the following: yarn

NOTE: It is highly suggested you add the export-statement to your .profile so it is added to your environment automatically.

💻 Installation

# install
yarn

# start storybook
yarn storybook

# build components
yarn build

▶️ Running with Console SM

See this documentation for more information. TLDR; Use the following environment variables to get a minimal setup running:

#build the project, go to the root directory (camunda-cloud-management-apps)
pnpm build

# camunda-cloud-management-apps/apps/console-sm-backend
NODE_ENV=local SERVICE_NAME=console-sm-backend CAMUNDA_CONSOLE_DISABLE_AUTH=true pnpm run start

# camunda-cloud-management-apps/apps/console-sm-frontend
pnpm run start:local

Navigate to localhost:4200 to open Console. Since the configmap content is just dummy information, fetching of all external data will fail (metrics for telemetry from webapps, ...).

💡 The environment variable CAMUNDA_CONSOLE_DISABLE_AUTH disables login for Console. That setup simplifies a local instance because there's no dependency that needs to be set up.

💡 The configmap content for the local instance is available in application.yaml.

🎁 Release

Official release

Both RC and final releases use the same publish-rc workflow. Run it from the GitHub Actions tab and select the release_type input.

The recommended two-step process:

1. Release candidate — run the workflow with release_type = RC. This publishes a prerelease to npm (tagged rc) and opens a PR named chore: bump version to X.Y.Z-rc.N. Due to branch-protection restrictions you must merge this PR manually.

2. Final release — once the RC is validated, run the workflow again with release_type = Final. This publishes the final package to npm, creates a GitHub release, and updates the changelog. Again, merge the resulting chore: bump version to X.Y.Z PR manually.

Local release

You can use YALC to deploy the package locally. Then you can use the package in another project by adding workspace: to the dependency version in the package.json.

🧪 Testing

Unit and interaction tests

Unit tests use Vitest and Storybook interaction tests use @storybook/test with a11y checks enabled.

yarn test:unit          # Vitest unit tests
yarn test:storybook     # Storybook interaction + a11y tests (requires a running Storybook)
yarn test:ci            # TypeScript check + unit tests + Storybook tests (used in CI)

These run automatically in CI on every push. New logic must have a *.test.ts unit test; new component states or user interactions must have a Storybook play function in the corresponding story.

Visual regression tests (VRT)

We use Playwright screenshot tests to be aware of any visual changes introduced by dependency updates or changes in the component code.

Running VRT locally

We run VRT inside a docker container to avoid different results caused by different platforms. Simply run:

yarn start:docker-storybook

then

yarn test:visual-regression:docker

The commands above will:

1. Build storybook.
2. Start a Playwright docker container with the name c4-visual-regression.
3. Serve storybook within the docker container.
4. Run the visual regression tests within the docker container.

When developing, it might not always be helpful to run all of these steps at once. You can find more granular scripts in the package.json.

Running VRT in the CI

There is a Visual regression tests workflow that is triggered automatically on push. You can also trigger it manually in the Actions tab.

If the workflow fails, you can find the test report by navigating to the workflow run summary, then scrolling down to the Artifacts section. Click on the artifact called Playwright report to download it, go to your downloads folder, then open the index.html file of the test report in your browser to view the report.

How to deal with failing tests

When a VRT fails, this can have two reasons:

1. A change was introduced unknowingly. In this case, have a look at the test report and check if the change was intended. If it is, proceed with 2.
2. You made a change to the UI on purpose. In this case you need to update the screenshot as follows.

Make sure you have the c4-visual-regression docker container running, or start it like described here. Then, have a look at the test report:

yarn report:visual-regression

Double-check that you don't apply any unwanted changes by looking at the difference that is highlighted in the failed test's report.

To update all screenshots, run:

yarn update:visual-regression:docker

The tests should now pass locally and in the CI. Commit and push the updated screenshot(s).