Component Libraries

What you can do

You already opened Maya's homepage hero from Widgets and started composing from the ten built-in cards — Text, Image, Video, Icon, Button, Divider, Embed, List, Accordion, Custom. That hero is a layout she built in RuleCMS. Her team also has a React hero they already ship on the site. This page is how that hero becomes a first-class palette card: a preview, its own attributes, drag onto the canvas, then publish.

Two everyday jobs:

• Put her own React hero on the palette. After we enable the package, a teammate registers the Library ID, sets it Active, and the card appears next to Text and Image. She drags it onto the Production Default Widget the way she already drags Image.
• Leave a host-only component as Custom. A booking form that already lives in her app, with no composer preview and no RuleCMS enablement, stays a Custom slot — a typed name her developer mounts on the host. That is a different door.

The library is scoped to her team. Other customers never load that package, and she never downloads theirs.

How a component library thinks

Three places have to agree on the same Library ID. We enable the npm package inside RuleCMS. Her team registers that id on the team page. Her site maps the same id in the libraries prop on RuleCMSWidgetProvider or RuleCMSWidgetServer. Miss any one of those and the palette stays empty, or the live page cannot render the hero.

Team registration does not load code by itself. Typing acme on Add Library does not install a package. The id has to match the library we already enabled. The Version field is her team's reference. The composer runs the version we enabled — a new npm tag does not appear until we take an update request. That request, the module shape, and the host map live on Build and enable.

Here is the case that surprises people. Maya registers the library, opens the composer, and looks for her hero. Status is Disabled, or the Library ID is off by one character from the id we enabled, or nobody refreshed the tab. The built-in ten are still there. Her group is not. Set Status to Active, match the id exactly, refresh — the list is cached for the browser session.

Disabled hides the library from the composer. It does not delete the widget JSON that already names her hero. Turn it back to Active and the card returns. A Trust column may show on the list. We set that during enablement. It is not self-assigned, and it is not on the form.

When she drags the card, the widget records the component type and the Library ID — acme/hero-banner can never collide with another team's hero-banner. Components without a library reference still resolve to the built-in RuleCMS set, the same as before.

Put Maya's React hero on the palette

Picture her homepage hero on the Production Default Widget — the widget created when the team was, in Production only. Today it is Text and Image. Her developers already published the React hero, and we have confirmed the library is live. This is the path from that confirmation to a card she can drag.

1. Open the organization → team. On the projects tab, under Team Resources, find the Component Libraries card. Library IDs are unique across all of RuleCMS — the card says so.
2. Click Add Library. If you only see View Libraries, you can open the list but cannot register — ask for Manage Component Libraries.
3. Enter the Library ID exactly as we enabled it — for example acme. It must be 3–64 characters, start with a lowercase letter, and use only lowercase letters, numbers, and hyphens. You cannot change it later.
4. Enter the Version we enabled, for the team's reference — for example 1.0.0. An optional Description shows on the list.
5. Set Status to Active. Disabled is the other choice — use it later to hide the library from the composer without deleting anything. Click Add Library.
6. Refresh any open composer tabs. Open the Production Default Widget. On the left, stay on Components. Her library is its own group — the title comes from the package, for example Acme Components. Drag Hero Banner onto the canvas the way you already drag Image.
7. Edit the attributes. Then publish. Live embeds do not change until you publish. That is a safe stop.

The list page shows every library for this team: Library ID, Version, Description, Status, and Trust. Edit updates version, description, and status. The Library ID field is locked. Open Documentation from that page to come back here.

An agent can register that same Library ID, and later change the version or hide the card, after you connect MCP. The steps are on Component libraries.

What to read next

This page is the story and the first walkthrough. The module, the enablement request, and the map her site types live on the page below.

• Build and enable — The ComponentLibraryModule contract, publish, the enablement request we need, version updates, the host libraries sample, and the troubleshooting table.
• RuleCMS Components — The ten built-in cards, and how a library sits beside them instead of replacing them.
• Mount Your Own Components — A typed name on the host for the Custom slot. No palette card, no RuleCMS enablement.
• The Composer — The palette, the canvas, and the Modify drawer — including Filters when a library looks missing.
• Widgets — Open Maya's hero from the dashboard. The Default Widget lives in Production.
• Publishing — Draft versus the snapshot a token fetches.
• Ask AI — Drop a library card the team already has enabled. It cannot register one.
• Development Integration — Preview a live Development draft with the same libraries map her published embeds use.

How this fits

A component library does not replace a widget, and it does not replace the ten built-in cards. It adds her team's React components as real palette cards next to them. Widgets is still how Maya opens the hero. Publishing is still how the site gets the snapshot.

Custom and Mount Your Own Components are the other door: a name her developer already registered on the host, a dashed box in the composer, no enablement. Use that when the component should stay in the app. Use a library when editors need a preview and attributes of their own.

We enable the package. She registers the Library ID. She drags the card. She publishes. Her site maps the same id so visitors see the hero she just placed.