@rulecms/widget-custom-element

Framework-agnostic custom element that renders a RuleCMS widget in any HTML page — WordPress, Angular, plain PHP, static sites, or any other host that can load a script tag.

Under the hood this package bundles:

• React + ReactDOM
• @rulecms/widget-react (fetch + layout renderer)
• @rulecms/source-components-react (text, image, video)

Hosts do not need npm, React, or a bundler.

Quick start (script tag)

After building (npm run build), serve dist/widget-custom-element.iife.js from your CDN:

<script src="https://cdn.example.com/widget-custom-element.iife.js"></script>

<rulecms-widget
  token="YOUR_CLIENT_TOKEN"
  published-key="ENVIRONMENT_ID---widget-…"
></rulecms-widget>

Set either published-key or ruleset-published-key (not both):

<rulecms-widget
  token="YOUR_CLIENT_TOKEN"
  ruleset-published-key="ENVIRONMENT_ID---ruleset-…"
  params='{"locale":"en","path":"/pricing"}'
></rulecms-widget>

Attributes (kebab-case; each has a JS property mirror):

| Attribute | Property | Description | |---|---|---| | token | token | RuleCMS client token (dev.… for live drafts) | | published-key | publishedKey | Published key, or live widget key with a dev. token | | ruleset-published-key | rulesetPublishedKey | {env}---ruleset-…, or a bare ruleset-… with a dev. token | | params | params | JSON object string for ruleset resolve. Invalid JSON shows an alert; the embed does not crash | | fallback-published-key | fallbackPublishedKey | Optional widget GET if resolve fails (network / 5xx) | | anonymous-id | anonymousId | Omit for the SDK default (rulecms_anon_id). anonymous-id="false" opts out | | endpoint | endpoint | Optional API origin override (tests / staging) |

The IIFE also exposes window.RuleCMS:

RuleCMS.define(); // no-op if already registered
RuleCMS.mount(document.getElementById('slot'), {
  token: '…',
  publishedKey: '…',
});
RuleCMS.mount(document.getElementById('ruleset-slot'), {
  token: '…',
  rulesetPublishedKey: '…',
  params: { locale: 'en', path: location.pathname },
});
RuleCMS.unmount(document.getElementById('slot'));

ESM / npm

npm install @rulecms/widget-custom-element

import { define, mount } from '@rulecms/widget-custom-element';

define(); // registers <rulecms-widget>

mount(document.querySelector('#slot'), {
  token: '…',
  publishedKey: '…',
});

mount(document.querySelector('#ruleset-slot'), {
  token: '…',
  rulesetPublishedKey: '…',
  params: { locale: 'en' },
});

Local demo

npm install
npm run dev

Opens example/index.html. Paste a token and either a published key or a ruleset published key from the RuleCMS dashboard and click Apply.

npm test
npm run lint
npm run typecheck
npm run build   # writes dist/*.js + .d.ts
npm run preview # optional static preview of dist

Publishing

Follow __docs__/RUNBOOK_version-bump-and-release.md.

When @rulecms/widget-react or @rulecms/source-components-react publishes, upgrade those dependencies here and release this package too.

Increment version

# Patch version (0.1.0 -> 0.1.1)
npm run version:patch

# Minor version (0.1.0 -> 0.2.0)
npm run version:minor

# Major version (0.1.0 -> 1.0.0)
npm run version:major

npm version also stamps src/version.ts so the IIFE RuleCMS.version matches package.json.

Publish to npm

Push the version tag. GitHub Actions publishes via trusted publishing (.github/workflows/publish.yml). Do not run npm run release or npm publish locally except for the first-ever version of a new package.

git push && git push --tags
npm view @rulecms/widget-custom-element version

WordPress / PHP sketch

wp_enqueue_script(
  'rulecms-widget',
  'https://cdn.example.com/widget-custom-element.iife.js',
  [],
  '0.1.0',
  true
);

// In the block / shortcode output:
echo '<rulecms-widget token="' . esc_attr($token) . '" published-key="' . esc_attr($key) . '"></rulecms-widget>';

Design notes

• Light DOM mount so host CSS variables (RuleCMS cssVariable brand tokens) and fonts still apply.
• Same fetch contract as @rulecms/widget-react (widget-cache for published tokens, rulecms.com for dev. tokens).
• Default component library is bundled; custom libraryId libraries are not pluggable in v0.1 (React npm SDK remains the path for custom libraries).

Related packages

| Package | Role | |---|---| | @rulecms/widget-react | React SDK (npm) | | @rulecms/source-components-react | Default text / image / video components | | @rulecms/widget-custom-element | This package — HTML custom element / CDN embed |

License

Proprietary — RuleCMS, LLC