@stackable-labs/embeddables

Embeddable web components and React bindings for Stackable extensions.

Installation

npm install @stackable-labs/embeddables

Usage — Script tag (IIFE)

Include the self-contained widget (bundles React internally):

<script src="https://unpkg.com/@stackable-labs/embeddables/dist/stackable-widget.js"></script>

Or, if your page already provides React, use the external build:

<script src="https://unpkg.com/@stackable-labs/embeddables/dist/stackable-widget.external.js"></script>

Usage — React

import { StackableWidget } from '@stackable-labs/embeddables/react';

For Next.js (includes "use client" directive):

import { StackableWidget } from '@stackable-labs/embeddables/react-next';

Styles

Import the stylesheet in your bundler or include it via CDN:

import '@stackable-labs/embeddables/styles';

<link rel="stylesheet" href="https://unpkg.com/@stackable-labs/embeddables/dist/embeddables.css" />

Build Outputs

| File | Format | Description | |---|---|---| | dist/stackable-widget.js | IIFE | Self-contained widget (includes React) | | dist/stackable-widget.external.js | UMD | Widget expecting React as external | | dist/react.js | ESM | React bindings for bundler consumers | | dist/react-next.js | ESM | React bindings (Next.js compatible) | | dist/embeddables.css | CSS | Widget styles |

Dev Overrides

For local development against a deployed host app, the SDK supports runtime bundleUrl overrides via query parameter. Append to your host app URL:

?_stackable_dev=ext-123%3Ahttps%3A%2F%2Fabc.trycloudflare.com

ExtensionSetup automatically detects the _stackable_dev param, validates the URL against a domain allowlist (localhost, trycloudflare.com, ngrok-free.app), and swaps the bundleUrl for matching extensions. A floating "🔧 Dev Mode" badge appears when overrides are active, with a "Clear" button to remove them.

No host app code changes required — this is built into ExtensionSetup.

See the CLI dev command for the full workflow.

Changelog

See npm version history.

License

SEE LICENSE IN LICENSE