@rulecms/widget-vue

Vue widget component for RuleCMS — the Vue 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-vue).

Installation

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

Peer dependency: vue >= 3.3.

Usage

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

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

<template>
  <RuleCMSWidgetProvider :token="token" :libraries="libraries">
    <RuleCMSWidget :published-key="publishedKey" :component-props="componentProps" />
  </RuleCMSWidgetProvider>
</template>

• 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-vue';

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

<RuleCMSWidget
  mode="pre-fetched"
  :published-key="publishedKey"
  :initial-data="data"
  :libraries="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 Vue 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 :published-key="publishedKey" :mounts="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-vue
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-vue version

License

Proprietary — RuleCMS, LLC