Registering a Component

Registering a component adds a developer-built component to the project so builders can use it on pages. You do this in the Custom Components manager by creating a new component, naming it, and defining its first version.

Steps to register

1. Navigate to Applications → Custom Components.

2. Click Add Component.

3. Enter a Name for the component.

4. Choose a Deployment Mode (see below).

5. Provide the mode-specific input (manifest URL or package upload).

6. Click Add to register.

Development vs. Production Mode

Development mode

The mode for testing and debugging before sharing. You provide a Manifest URL pointing at the component's live build. The builder loads the component straight from that address — changes you redeploy at that URL show up without a formal release.

Warning: Because the test version renders live from its Manifest URL, a redeploy at that address silently changes what everyone testing the component sees. There is no snapshot until promotion.

Production mode

The mode for a stable, optimized component ready for use across the project. You upload a packaged build as a .zip archive and can add a version tag and release notes.

When you upload a production build, the platform runs automated checks:

The Add button stays disabled until the upload finishes and all checks pass.

The Test Version

The test version is a single, live, in-progress version defined by a Manifest URL. The builder loads it straight from that address, so whatever your developer redeploys there is what the test version shows — no upload, no numbering.

From the component's detail view you can:

• Edit — update the Manifest URL. The component reloads from the new address.

• Move to production — promote the test version to a numbered production version.

Note: Only one test version exists at a time. While a test version is pending promotion, you cannot start another one. Promote or discard the pending test version first.

Production Versions

A production version is a fixed snapshot of the component, created by uploading a packaged build. Each one is numbered and kept in the version history — it never changes after creation. Apps pinned to a production version keep rendering exactly that build.

When creating a production version you can add:

• Version tag — a short label (e.g., v1.2.0)

• Release notes — a description of what changed

Promoting the Test Version to Production

1. In the component's detail view, click Move to production on the test version row.

2. Upload the component's packaged build (the .zip archive of your built code).

3. Optionally add a version tag and release notes.

4. Click Deploy. The platform deploys it as the next numbered production version.

Warning: Promotion requires a packaged build, not the test URL. Moving to production takes an uploaded package — not a capture of the running test URL. Make sure the package you upload matches what you tested. The two are separate artifacts.

Once promoted, the development version section disappears until you start a new test version.

Content Security Policy (CSP) for Dev Hosts

If the app's content security policy blocks the host serving your Manifest URL, a dialog appears naming the blocked host and offering to allow it. Confirming:

1. Adds the host to the app's allowed list.

2. Reloads the page so the change takes effect.

3. Reopens the create dialog with your entered URL still filled in.

Until a builder allows the host, the component can't be loaded from that address.

Note: An unreachable URL and a blocked URL look different. An unreachable address produces a validation error asking for a valid URL. A reachable-but-blocked address produces the allow-and-reload dialog. Only the second case is fixed by allowing the host.

Frequently Asked Questions

Can I promote directly to production without testing via a manifest URL first?

Yes. When creating a component you can choose Production mode directly, upload a packaged build, and skip the development test version entirely. This is appropriate when you've already tested the component outside the platform.

What if my production upload fails the file checks?

The Add button stays disabled until all checks pass. The dialog shows which specific checks failed — manifest missing, component type not defined, UI code absent, or icon unresolved. Fix the corresponding issue in your package and re-upload.

Can I roll back to an older production version?

You can't roll back the registered component itself, but a Custom block on a page can be pinned to any specific version in the version history. Pin affected blocks to an older version if a new production version has a regression. See Using in the Builder.

Does promoting a new production version automatically update all pages using this component?

Only if those pages' Custom blocks are set to Latest deployed as the version. Blocks pinned to a specific version number are unaffected by a promotion. This is why pinning is important when you need to isolate a page from future releases.

Related Pages

• Custom Components Overview — the full lifecycle and the two-halves model

• Using in the Builder — placing and configuring the component on a page