Development Integration

What you can do

You already have a workspace from Getting Started. Picture Maya's homepage hero. After Get Started the Default Widget is already in Production. Development is empty. That is expected. This page is how she previews a Development draft on her own site — as soon as she saves.

Two everyday jobs:

• See the Development hero on her local site. She creates the hero in Development, opens the Integrate tab, copies the dev. token and the draft widget-… key, and pastes the snippet. Save in the composer. Refresh the page. There is no publish step.
• Embed the same draft on a page that is not React. The HTML Custom Element Embed accepts a dev. token and that draft key the same way.

She builds with the ten built-in cards — Text, Image, Video, Icon, Button, Divider, Embed, List, Accordion, Custom — or a library she registered. Ask AI can compose. It cannot publish. Development has nothing to publish anyway.

How it thinks

The composer edits the draft. Development streams that draft. Staging and Production fetch a published snapshot. Those two paths use different tokens and different keys. Mix them and the request goes to the wrong host.

A dev. token plus a draft widget-… key loads the live composer. A Staging or Production token plus a published key — {environmentId}---widget-… — loads the snapshot. @rulecms/widget-react picks the host from the token. Omit endpoint.

Here is the case that surprises people. Maya opens Development looking for the Default Widget and the list is empty. That is expected. Get Started — and every extra team — creates the Default Widget in Production, the environment she lands in. Extra projects get a Production Default Widget and no tokens. To preview the hero in Development she creates it there, or composes a new widget. There is no Copy To Staging or Production, and Promote does not copy Production back into Development. Promote copies the draft to the next environment. Copy To is only for extra environments she named herself. See Widgets and Projects, Environments & Tokens.

Preview Maya's homepage hero

You do this on the widget management page in Development. The tab is labeled Integrate, not Publish. The heading on that tab is Integrate in your app.

1. Switch the environment to Development — the switcher under the project name. Development is empty after Get Started. On the orange Widgets card, click Add. Name it “Homepage hero” if you like. Submit Create Widget.
2. Open the widget. You land on the management page. Open the Integrate tab.
3. Copy the Widget key (draft). It looks like widget-…. Do not use a Staging or Production published key here.
4. Open Tokens from that tab. Select Default App and Development. Create or copy an enabled token. It must start with dev.. Older tokens without the prefix must be regenerated — without it, @rulecms/widget-react treats the token as published and will not load drafts.
5. Install @rulecms/widget-react 22.11.0 or later. Paste the snippet from Integrate. The token goes on the provider. The draft key goes on publishedKey={widgetKey}. Omit endpoint — the SDK calls https://rulecms.com for dev. tokens.
6. Open the composer, drop in the hero, save, and refresh her local site. Shared and embedded collections in Development travel with the next fetch. That is a safe stop.

import { RuleCMSWidgetProvider, RuleCMSWidget } from '@rulecms/widget-react';
import * as sourceComponents from '@rulecms/source-components-react';

const token = process.env.NEXT_PUBLIC_RULECMS_DEV_TOKEN; // must start with "dev."
const widgetKey = 'widget-…';

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

For React Server Components, use RuleCMSWidgetServer or fetchRuleCMSWidget with the same token and key — routing is identical. Server Rendering with Pre-fetched Mode walks through the fetchRuleCMSWidget path.

If the hero uses a team library, map it on the provider the same way a published embed does — see Component Libraries. A Custom slot that should render a host component needs Mount Your Own Components.

When you reach for Staging or Production

The local preview is the live draft. When Maya wants a stable, cacheable release:

1. Promote to Staging copies the draft into Staging. It does not publish. On Staging, Promote to Production does the same for Production. Clicks are on Widgets.
2. Publish in that environment. That creates the snapshot and the published key.
3. Switch the app to a Staging or Production token — no dev. prefix — and that published key. The SDK calls https://widget-cache.rulecms.com automatically.

Widget Edit Links need a published embed. The R badge does not appear on a Development draft preview.

When you call the HTTP API yourself

You can skip the React SDK and fetch the draft — another framework, a script, a host that is not React:

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

• Query names are token and widgetKey.
• The response shape matches the published widget API.
• Responses are not cached (Cache-Control: no-store).
• A 401 that says Development tokens must start with "dev." means regenerate the token, or upgrade @rulecms/widget-react if you are older than 22.11.0.

When something goes wrong

What to read next

This page is the story and the first embed. Tokens, publish, and the other hosts live on the pages below.

• Projects, Environments & Tokens — Copy the dev. token. Extra projects get a Production Default Widget and no tokens — add those yourself.
• Publishing — How the hero becomes the snapshot a Staging or Production token fetches. Development stays on Integrate.
• HTML Custom Element Embed — The same dev. token and draft key, without a React host.
• API Reference — The published GET. Same response fields; different token, key, and host.
• Component Libraries — Map a team library on the provider so the preview can render it.
• Mount Your Own Components — A Custom slot that should render a component from her app.

How this fits

A Development embed does not replace a published widget. It is how Maya sees the draft before she promotes and publishes. Widgets is how she creates the hero. Publishing is how the site gets a snapshot. Tokens live on Projects, Environments & Tokens.

Create the homepage hero in Development. Open Integrate. Copy the dev. token and the draft widget-… key. Save. Refresh. When the hero is ready, promote the draft, then publish.