@rulecms/widget-svelte

Svelte widget component for RuleCMS — the Svelte counterpart of @rulecms/widget-react.

Fetches a widget by token + key and renders the itemList layout tree through registered component libraries (default: @rulecms/source-components-svelte).

Installation

npm install @rulecms/widget-svelte @rulecms/source-components-svelte

Peer dependency: svelte >= 5.0.

Usage

<script>
  import { RuleCMSWidget, RuleCMSWidgetProvider } from '@rulecms/widget-svelte';
  import * as sourceComponents from '@rulecms/source-components-svelte';

  const token = 'your-token';
  const publishedKey = 'your-widget-key';
  const libraries = { default: sourceComponents };
  const componentProps = {
    'b721c4e2-…': { onClick: (event) => console.log('cta', event) },
  };
</script>

<RuleCMSWidgetProvider {token} {libraries}>
  <RuleCMSWidget {publishedKey} {componentProps} />
</RuleCMSWidgetProvider>

• Staging/Production: plain token + environmentId---widget-… published key → widget-cache
• Development: dev.… token + draft widget-… key → rulecms.com live drafts

Same routing rules as @rulecms/widget-react.

Server-side rendering

Fetch widget data on the server (or at build time), then render with pre-fetched data so images and content appear in the initial HTML.

import { fetchRuleCMSWidget } from '@rulecms/widget-svelte';

const data = await fetchRuleCMSWidget({
  publishedKey: process.env.RULECMS_PUBLISHED_KEY,
  token: process.env.RULECMS_TOKEN,
});

<RuleCMSWidget
  mode="pre-fetched"
  {publishedKey}
  initialData={data}
  {libraries}
/>

No token is needed on the client in pre-fetched mode — the widget does not refetch in the browser. Pre-fetched mode uses CSS breakpoint variants so server HTML matches all viewport widths.

Host componentProps

Pass extra props — a click handler, a callback — to one component instance by its column id. A key may be a bare id (every copy of a repeated collection) or a /-path of enclosing collection columns ending at the target (one embedding). Longest match wins.

r-button reads onClick from the bag. The renderer never inspects the contents. In development, a key that addresses no column in the widget is printed once so typos are visible while building.

Host mounts

Register a Svelte component from your app so a Custom (r-mount) slot in the composer can render it by name. The name is a map key, not a string that becomes code. A miss is a placeholder.

<RuleCMSWidget publishedKey={publishedKey} {mounts} />

const mounts = { 'booking-form': BookingForm };

Tell the marketer the exact name and the props the component reads. Event handlers still go through componentProps at that column's id — authored prop rows cannot become onClick. See __docs__/CONTRACT_mounts.md and Mount Your Own Components.

Develop locally

cd widget-svelte
npm install
npm test
npm run lint
npm run typecheck
npm run build

Publishing

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

Increment version

npm run version:patch
npm run version:minor
npm run version:major

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 (npm cannot attach a trusted publisher until the package exists).

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

License

Proprietary — RuleCMS, LLC