@rlse/widget

Multi-framework release notes widget for rlse.dev. Works with React, Vue, Angular, Svelte, Astro, and vanilla JavaScript.

Features

• Multi-framework: React, Vue, Angular, Svelte, Astro, Vanilla JS
• Three variants: Floating button, embedded panel, dropdown menu
• Smart triggers: Manual button, auto-popup on new releases, or both
• Unread badge: Shows count of unseen changes
• App filtering: Show changes for a specific application or all
• Theming: Light, dark, or auto (follows system preference)
• Customizable: Position, colors, labels, and more

Installation

npm install @rlse/widget

Quick Start

React / Next.js

import { RlseWidget } from '@rlse/widget';

function App() {
  return (
    <>
      <YourApp />
      <RlseWidget orgSlug="your-org-slug" />
    </>
  );
}

Vue / Nuxt

<script setup>
import { RlseWidget } from '@rlse/widget/vue';
</script>

<template>
  <RlseWidget org-slug="your-org-slug" />
</template>

Angular

import { RlseWidgetComponent } from '@rlse/widget/angular';

@Component({
  imports: [RlseWidgetComponent],
  template: `<rlse-widget orgSlug="your-org-slug"></rlse-widget>`
})

Svelte / SvelteKit

<script>
  import { RlseWidget } from '@rlse/widget/svelte';
</script>

<RlseWidget orgSlug="your-org-slug" />

Astro

---
import { RlseWidget } from '@rlse/widget/react'; // or vue/svelte
---

<RlseWidget orgSlug="your-org-slug" client:load />

Vanilla JS (CDN)

<script>
  window.rlseWidgetConfig = {
    orgSlug: 'your-org-slug',
  };
</script>
<script async src="https://rlse.dev/widget.js"></script>

Configuration

Required

| Option | Type | Description | | --------- | -------- | ------------------------------------ | | orgSlug | string | Your organization slug from rlse.dev |

Optional

| Option | Type | Default | Description | | --------------- | -------------------------------------------------------------- | ----------------- | ------------------------------------- | | appSlug | string | — | Filter to a specific application | | trigger | 'auto' \| 'manual' \| 'both' | 'manual' | How the widget opens | | position | 'bottom-right' \| 'bottom-left' \| 'top-right' \| 'top-left' | 'bottom-right' | Button position | | theme | 'light' \| 'dark' \| 'auto' | 'auto' | Color theme | | limit | number | 10 | Max changes to display | | triggerLabel | string | "What's New" | Button text | | modalTitle | string | "Release Notes" | Modal header | | primaryColor | string | #3b82f6 | Accent color (hex) | | autoShowAfter | number | 7 | Days before auto-popup triggers again |

Widget Variants

RlseWidget (Floating Button)

A floating trigger button that opens a modal. Best for standalone pages.

import { RlseWidget } from '@rlse/widget';

<RlseWidget
  orgSlug="acme-corp"
  appSlug="dashboard"
  trigger="both"
  position="bottom-right"
  theme="auto"
  limit={5}
  triggerLabel="What's New"
  modalTitle="Release Notes"
  primaryColor="#3b82f6"
/>;

RlseWidgetEmbed (Inline Panel)

An embeddable panel for sidebars or dedicated pages. Great for dashboards.

import { RlseWidgetEmbed } from '@rlse/widget';

<RlseWidgetEmbed
  orgSlug="acme-corp"
  appSlug="dashboard"
  showHeader={true}
  showFooter={true}
/>;

RlseWidgetMenu (Dropdown)

A compact dropdown for navigation bars. Perfect for user menus.

import { RlseWidgetMenu } from '@rlse/widget';

<RlseWidgetMenu
  orgSlug="acme-corp"
  appSlug="dashboard"
  triggerLabel="What's New"
/>;

## Trigger Modes

- **`manual`** — Floating button always visible; click to open. Unread badge shows unseen count.
- **`auto`** — No button; modal auto-opens on first visit after new releases, respecting `autoShowAfter`.
- **`both`** — Floating button plus auto-popup on new releases.

## How "New" Tracking Works

The widget uses browser `localStorage` to track seen changes — no backend or login required.

- **Key**: `rlse_widget_{orgSlug}_seen`
- **Value**: Array of seen change IDs
- Per-device tracking (phone and laptop tracked independently)

## Styling

Use `primaryColor` to match your brand:

```tsx
<RlseWidget orgSlug="acme-corp" primaryColor="#ff6b6b" />

Troubleshooting

Widget not appearing

1. Verify orgSlug is correct
2. Ensure your organization has published public changes
3. Check the browser console for errors

Auto-popup not triggering

1. Open DevTools → Application → Local Storage
2. Clear rlse_widget_* keys to reset seen state
3. Verify autoShowAfter is set as expected

Security

• Only public changes are surfaced — no authentication required
• localStorage data stays entirely client-side
• CORS headers restrict the widget API to read-only operations

Support

• Email: [email protected]
• Dashboard: Settings → Widget Embed
• Full documentation: https://rlse.dev/docs/widget