Component Libraries

What are component libraries?

Out of the box, the RuleCMS composer offers a standard set of widgets — text, images, carousels, forms, and more. Component libraries let your team go further: your developers package your own React components as a versioned library, and those components become first-class citizens in RuleCMS. Your content editors see them in the composer palette, drag them onto pages, edit their attributes, and publish — exactly like built-in widgets. Your websites and apps then render them with pixel -perfect fidelity, including full server-side rendering.

Each library is scoped to your team. Your components are never visible to, or loaded by, any other RuleCMS customer — and you never download theirs.

Why use them?

• Your brand, your components. Hero sections, product cards, announcement banners — anything your design system defines can become a CMS-editable widget instead of a hardcoded page section.
• Editors ship without engineers. Once a component is in your library, content changes (copy, images, layout attributes) happen in the composer — no code deploy needed.
• True isolation. Libraries are loaded per team and only when a page actually uses them. Other customers' code never reaches your users, and yours never reaches theirs.
• SSR and React Server Components supported. Your own site can render CMS-managed pages that use your components with full server-side rendering — no client-only compromises.
• Independent versioning. Your library ships on its own release cadence as a normal npm package, separate from RuleCMS releases and separate from your site deploys.

How it works

Your developers publish an npm package that exports your components in the @rulecms/widget-react library format. The library gets a globally unique Library ID (for example acme). When an editor drags one of your components onto a page, the widget configuration records both the component type and your Library ID — so acme/hero-banner can never collide with another library's hero-banner.

Three parties are involved in the setup:

Step 1 — Build your component library

A component library is a standard npm package whose module exports three things: a manifest, a components map (the render surface), and an optional editor surface (what the composer needs — palette cards, drag previews, and attribute editing metadata). The shape is defined by the ComponentLibraryModule contract in @rulecms/widget-react. Conformance is structural: your package does not need a runtime dependency on RuleCMS packages (a devDependency-only type check is enough).

// src/index.ts — the module itself IS the library
import packageJson from '../package.json';

export const manifest = {
  id: 'acme',                    // your Library ID
  version: packageJson.version,
  reactPeerRange: '>=16.8.0',
};

// Render surface: component type -> renderable entry
export const components = {
  'hero-banner': heroBannerEntry,
  'product-card': productCardEntry,
};

// Editor surface: what the RuleCMS composer shows your editors
export const editor = {
  previewComponents: { /* drag preview thumbnails */ },
  previewCardGroups: [
    {
      title: 'Acme Components',
      showInitially: true,
      cards: [{ title: 'Marketing', entries: [/* palette entries */] }],
    },
  ],
  componentMetadata: { /* attribute editing configuration */ },
};

Key conventions:

• react and react-dom must be peer dependencies — never bundled into your library.
• Component type ids are kebab-case (for example hero-banner). They only need to be unique within your library; namespacing across libraries is automatic.
• Without the editor export your components still render in published widgets, but they will not appear in the composer palette — include it if editors should be able to add your components to pages.
• Ship an ESM build (CJS additionally is fine) with TypeScript declarations.

Step 2 — Publish your package

Publish the library to npm (a public package, or a private registry we can be granted access to). Standard semantic versioning applies. Every version you want available in RuleCMS goes through the enablement or update request below.

Step 3 — Request enablement from the RuleCMS team

The RuleCMS platform loads only libraries that have been reviewed and wired into the platform by us. This is a security and isolation guarantee for every customer: nothing executes inside RuleCMS that we have not enabled. So before your library can appear in the composer, you file an enablement request with the RuleCMS team.

Send the request to your RuleCMS contact (or support channel) using the following format:

Subject: Component library enablement request — <your library ID>

1. Library ID (required)
   The globally unique id, e.g. "acme".
   Format: 3-64 chars, lowercase letters/numbers/hyphens,
   must start with a lowercase letter. Immutable once created.

2. npm package name (required)
   e.g. @acme/rulecms-widgets

3. Version to enable (required)
   Exact published version, e.g. 1.2.0

4. Registry access (required if not public npm)
   How we can install the package: public npm / private registry
   credentials / access instructions.

5. Organization and Team (required)
   Your RuleCMS organization name and the team(s) that should be
   able to use this library.

6. Component inventory (required)
   List each component type id with a one-line description,
   e.g. "hero-banner — full-width hero with CMS-editable heading".

7. React version range (required)
   The reactPeerRange your library supports, e.g. ">=16.8.0".

8. Editor surface included? (required)
   Yes/No — whether the package exports the editor surface so
   components appear in the composer palette.

9. Source access for review (recommended)
   Repository link or read access so we can review the library
   before enabling it.

10. Technical contact (required)
    Name and email of the developer we can reach with questions.

What happens next:

• We review the package (contract conformance, bundle hygiene, no bundled React, reasonable size).
• We install it into the RuleCMS platform and wire up your Library ID. This ships with a platform deploy, so allow for our release cycle — your contact will confirm the timeline.
• We confirm when the library is live, at which point Step 4 below activates it for your team.

Step 4 — Register the library for your team

Once we confirm enablement, a team admin (with component library permissions) registers it in RuleCMS:

1. Go to your team page and open Component Libraries.
2. Click Add Library and enter:
   • Library ID — exactly the id we enabled (for example acme). It must match; this is what links your registration to the enabled package.
   • Version — the enabled version, for your team's reference.
   • Status — set to Active. Setting it to Disabled later immediately hides the library from the composer without deleting anything.
3. Save, then refresh any open composer tabs.

If you don't see the Component Libraries page or the Add Library button, ask your team admin for access — these actions are permission gated.

Step 5 — Use your components in the composer

After registration, open any widget in the composer:

• Your library appears as its own card group in the left palette (the group title comes from your library's editor surface).
• Drag your components onto the canvas like any built-in widget. The widget configuration automatically records your Library ID.
• Attribute editing, previews, version comparison, and publishing all work the same as with built-in components.

If the palette group doesn't appear: confirm the registration status is Active, the Library ID matches exactly, we have confirmed enablement, and you have refreshed the page (the library list is cached per browser session).

Step 6 — Render published widgets in your own apps

Your websites and apps render RuleCMS widgets with @rulecms/widget-react (v15 or later). Register your library alongside the default one — your app installs your package directly from npm, so no RuleCMS request is needed for this side:

import * as sourceComponents from '@rulecms/source-components-react';
import * as acmeWidgets from '@acme/rulecms-widgets';

<RuleCMSWidgetProvider
  token={token}
  libraries={{
    default: sourceComponents,
    acme: acmeWidgets,            // eager import: full SSR support
    // or: acme: () => import('@acme/rulecms-widgets')  // code-split
  }}
>
  <RuleCMSWidget publishedKey={publishedKey} />
</RuleCMSWidgetProvider>

For React Server Components, pass the same map to RuleCMSWidgetServer via its libraries prop. Libraries are only ever loaded when a widget's configuration actually references them, so registering a library costs nothing on pages that don't use it.

Troubleshooting

Good to know

• Library IDs are immutable and globally unique across all of RuleCMS. Choose one that identifies your organization (for example your brand name) — it becomes part of every widget configuration that uses your components.
• Disabling is instant and reversible. Setting a registration to Disabled hides the library from the composer for your team without touching existing widget configurations.
• The trust tier is managed by us. You may notice a trust field on your library registration; it is set by the RuleCMS team as part of the enablement review and cannot be self-assigned.
• Existing widgets are unaffected. Components without a library reference always resolve to the standard RuleCMS widget library, exactly as before.