@rlse/widget

@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

• Verify orgSlug is correct
• Ensure your organization has published public changes
• Check the browser console for errors

Auto-popup not triggering

• Open DevTools → Application → Local Storage
• Clear rlse_widget_* keys to reset seen state
• 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: [e-mail]
• Dashboard: Settings → Widget Embed
• Full documentation: https://rlse.dev/docs/widget