@beeport/widget

BeePort feedback widget — npm package for programmatic installation.

Injects the same CDN-hosted widget as the <script> tag installation, but lets you control initialisation from your application code.

Installation

npm install @beeport/widget

Usage

Named imports (recommended — tree-shakeable)

import { init, destroy, open, close } from '@beeport/widget';

// Initialise the widget
init({ project: 'prj_abc123' });

// Programmatically open/close the feedback panel
open();
close();

// Remove all widget elements and reset (allows re-init)
destroy();

Namespace import

import BeeportWidget from '@beeport/widget';

BeeportWidget.init({ project: 'prj_abc123' });
BeeportWidget.open();
BeeportWidget.close();
BeeportWidget.destroy();

CommonJS

const { init, destroy, open, close } = require('@beeport/widget');
init({ project: 'prj_abc123' });

API

init(config)

Loads and initialises the BeePort widget by injecting the CDN script tag into document.body.

Idempotent — calling init() multiple times is safe; subsequent calls are no-ops.

Throws Error if called outside a browser environment (SSR guard).

init({
  project: 'prj_abc123',    // Required. Your project key.
  theme: 'auto',            // Optional. 'light' | 'dark' | 'auto'. Default: browser default.
  position: 'bottom-right', // Optional. 'bottom-right' | 'bottom-left'. Default: 'bottom-right'.
  accent: '#f3c744',        // Optional. CSS colour string. Default: BeePort gold.
  text: 'Feedback',         // Optional. Button label. Default: 'Feedback'.
});

destroy()

Removes all widget DOM elements (script tag, trigger button, iframe card, mobile sheet) and resets the loaded flag so init() can be called again.

Safe to call before init() or in non-browser environments (no-op).

open()

Programmatically opens the feedback panel by dispatching a beeport:open custom event on window.

Safe to call in non-browser environments (no-op).

close()

Programmatically closes the feedback panel by dispatching a beeport:close custom event on window.

Safe to call in non-browser environments (no-op).

TypeScript

Full TypeScript types are included. The BeePortConfig interface is exported for use in your own code:

import { init, type BeePortConfig } from '@beeport/widget';

const config: BeePortConfig = {
  project: 'prj_abc123',
  theme: 'dark',
};

init(config);

Framework examples

React

import { useEffect } from 'react';
import { init, destroy } from '@beeport/widget';

export function FeedbackWidget() {
  useEffect(() => {
    init({ project: 'prj_abc123', theme: 'auto' });
    return () => destroy();
  }, []);

  return null;
}

Vue

import { onMounted, onUnmounted } from 'vue';
import { init, destroy } from '@beeport/widget';

export function useFeedbackWidget(project: string) {
  onMounted(() => init({ project }));
  onUnmounted(() => destroy());
}

SSR

The package is SSR-safe. No window or document access occurs at import time — all browser APIs are only accessed inside function bodies. init() throws a descriptive error if called server-side; all other functions are silent no-ops.

Output formats

• ESM (dist/index.js) — for bundlers and modern environments
• CJS (dist/index.cjs) — for Node.js and legacy bundlers
• Types (dist/index.d.ts) — TypeScript declarations

sideEffects: false is set in package.json for reliable tree-shaking.

Script tag alternative

If you don't use a bundler, load the widget directly from the CDN:

<script
  src="https://cdn.beeport.ai/widget.js"
  data-project="prj_abc123"
  data-theme="auto"
></script>