Development Integration

What this is for

Use this when you are building a website or app that embeds RuleCMS widgets and you want composer edits in the Development environment to show up on your site as soon as you save — without publishing to Staging or Production.

Staging and Production still use publish + published keys + the cache layer. Development uses a separate path that reads the live draft widget and its collections.

How it differs from Staging / Production

Prerequisites

• A RuleCMS team with a Development environment (created at signup).
• @rulecms/widget-react 22.11.0 or later in your app.
• Your component libraries registered on the provider (same as published embeds — see Component Libraries).

Step 1 — Get a Development token

1. In RuleCMS, open …/app-project-env-tokens (or open Tokens from the Development environment home).
2. Select your app and the Development environment.
3. Create or regenerate an enabled token. It must start with dev. (for example dev.AbCd…).
4. Store it as a secret in your app (env var / secrets manager).

Token management overview: Projects, Environments & Tokens.

Step 2 — Get the widget key

1. Open the widget in the Development environment composer or widget manage page.
2. Copy the widget key. It looks like widget-9a31b6c8-….

Do not use a Staging/Production published key ({environmentId}---widget-…) with a dev. token.

Step 3 — Embed in your app

Pass the Development token and the draft widget key. Omit endpoint — the SDK chooses https://rulecms.com automatically.

import { RuleCMSWidgetProvider, RuleCMSWidget } from '@rulecms/widget-react';
import * as sourceComponents from '@rulecms/source-components-react';
// plus any team libraries you use…

const token = process.env.NEXT_PUBLIC_RULECMS_DEV_TOKEN; // starts with "dev."
const widgetKey = 'widget-…'; // draft key from Development

export function DevPreview() {
  return (
    <RuleCMSWidgetProvider
      token={token}
      libraries={{ default: sourceComponents }}
    >
      <RuleCMSWidget publishedKey={widgetKey} />
    </RuleCMSWidgetProvider>
  );
}

The prop is still named publishedKey for API compatibility. In Development mode its value is the draft widget key.

For React Server Components, use RuleCMSWidgetServer or fetchRuleCMSWidget with the same token and key — routing is identical.

Step 4 — Edit and refresh

1. Change the widget or a nested collection in the RuleCMS composer.
2. Save.
3. Refresh (or remount) your consuming page.
4. You should see the new content immediately — no publish step.

Shared and embedded collections in Development are included automatically. Editing a collection used by the widget updates the next fetch the same way.

Going to Staging or Production

When you are ready for a stable, cacheable release:

1. Promote or recreate content in Staging/Production and publish.
2. Switch your app to a Staging/Production token (no dev. prefix) and the widget's published key.
3. widget-react will call the published API through widget-cache automatically.

Optional: call the HTTP API directly

You can skip the React SDK and call the draft endpoint yourself (for example from another framework):

GET https://rulecms.com/api/v1/c/dev/widget/get?token=dev.…&widgetKey=widget-…

• Response shape matches the published widget API.
• Responses are not cached (Cache-Control: no-store).
• The token must start with dev. and belong to a non-Staging / non-Production environment.

Troubleshooting

Related docs

• HTML Custom Element Embed (any HTML site — no React host)
• Projects, Environments & Tokens
• API Reference (published path)
• Publishing
• Mount Your Own Components (Custom slot + mounts)
• Component Libraries
• Engineering: React derived state vs useEffect
• Engineering blog