@rulecms/widget-angular

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

Installation

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

Peer dependencies: @angular/core and @angular/common >= 17.

Usage

import { Component } from '@angular/core';
import { RuleCMSWidgetComponent, RuleCMSWidgetProviderComponent } from '@rulecms/widget-angular';
import * as sourceComponents from '@rulecms/source-components-angular';

@Component({
  standalone: true,
  imports: [RuleCMSWidgetProviderComponent, RuleCMSWidgetComponent],
  template: `
    <rulecms-widget-provider [token]="token" [libraries]="libraries">
      <rulecms-widget [publishedKey]="publishedKey" [componentProps]="componentProps" />
    </rulecms-widget-provider>
  `,
})
export class PageComponent {
  token = 'your-token';
  publishedKey = 'your-widget-key';
  libraries = { default: sourceComponents };
  componentProps = {
    'b721c4e2-…': { onClick: (event: Event) => console.log('cta', event) },
  };
}

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

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

<rulecms-widget
  mode="pre-fetched"
  [publishedKey]="publishedKey"
  [initialData]="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.

<rulecms-widget
  [publishedKey]="publishedKey"
  [componentProps]="componentProps"
/>

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 an Angular 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.

<rulecms-widget
  [publishedKey]="publishedKey"
  [mounts]="mounts"
/>

mounts = { 'booking-form': BookingFormComponent };

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-angular
npm install
npm test
npm run lint
npm run typecheck
npm run build

Publishing

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

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

Publish to npm

Push the version tag. GitHub Actions publishes dist/ 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-angular version

License

Proprietary — RuleCMS, LLC