@rulecms/widget-react

React widget component for RuleCMS

Installation

npm install @rulecms/widget-react

Usage

import { RuleCMSWidget } from '@rulecms/widget-react';

function App() {
  return (
    <RuleCMSWidget publishedKey="your-widget-key" />
  );
}

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.

1. Fetch on the server

import { fetchRuleCMSWidget } from '@rulecms/widget-react/server';
import { RuleCMSWidget } from '@rulecms/widget-react';

// Use a server-only env var — never NEXT_PUBLIC_* for the token
const data = await fetchRuleCMSWidget({
  publishedKey: 'your-widget-key',
  token: process.env.RULECMS_TOKEN!,
  endpoint: process.env.RULECMS_ENDPOINT, // optional; widget-cache recommended
  fetchOptions: {
    // Next.js App Router cache control, e.g.:
    next: { revalidate: 60 },
  },
});

2. Render with pre-fetched data

<RuleCMSWidget mode="pre-fetched" publishedKey="your-widget-key" initialData={data} />

No token is needed on the client in pre-fetched mode — the widget does not refetch in the browser.

Next.js App Router example

// app/page.tsx
import { fetchRuleCMSWidget } from '@rulecms/widget-react/server';
import { RuleCMSWidget } from '@rulecms/widget-react';

export default async function Page() {
  const data = await fetchRuleCMSWidget({
    publishedKey: process.env.RULECMS_PUBLISHED_KEY!,
    token: process.env.RULECMS_TOKEN!,
    fetchOptions: { next: { revalidate: 60 } },
  });

  return (
    <RuleCMSWidget mode="pre-fetched" publishedKey={process.env.RULECMS_PUBLISHED_KEY!} initialData={data} />
  );
}

Endpoint recommendation

For production, point endpoint at the widget-cache service (https://widget-cache.rulecms.com) for faster server fetches. The default (relative /api/v1/c/widget/get) is unchanged for backward compatibility.

Zero-JS widgets with RuleCMSWidgetServer (App Router)

On Next.js App Router (or any React Server Components environment), RuleCMSWidgetServer fetches and renders the widget entirely on the server — no widget JavaScript ships to the browser:

// app/page.tsx — a Server Component (no 'use client')
import { RuleCMSWidgetServer } from '@rulecms/widget-react/server';

export default function Page() {
  return (
    <RuleCMSWidgetServer
      publishedKey={process.env.RULECMS_PUBLISHED_KEY!}
      token={process.env.RULECMS_TOKEN!}
      fetchOptions={{ next: { revalidate: 60 } }}
      errorFallback={<p>Content is temporarily unavailable.</p>}
    />
  );
}

Error semantics: if the fetch fails, the component logs the error and renders errorFallback (default: nothing) — a CMS outage never breaks your page.

Which server API should I use?

| | RuleCMSWidgetServer | fetchRuleCMSWidget + mode="pre-fetched" | |---|---|---| | Widget JS in browser | none | yes (hydrates) | | Environments | App Router / RSC only | any React SSR (App/Pages Router, Remix, Express…) | | Data control | fetch happens inside the component | you own the fetch (share data, custom caching) |

See __docs__/move-to-ssr/PLAN-move-to-ssr.md for the full SSR roadmap.

Development

Install dependencies

npm install

Run development mode

npm run dev

Run tests

npm test

Run Storybook

npm run storybook

Build for production

npm run build

Publishing

Increment version

# Patch version (1.0.0 -> 1.0.1)
npm run version:patch

# Minor version (1.0.0 -> 1.1.0)
npm run version:minor

# Major version (1.0.0 -> 2.0.0)
npm run version:major

Publish to npm

npm run release

License

MIT