@iffu/steppie-widget

v0.1.3

Published

2 months ago

Steppie embeddable chat widget — React component and CDN script

Downloads

0High
0Medium
0Low

iffu

steppie chat widget react customer-support

`@iffu/steppie-widget`

Embeddable Steppie chat widget for customer sites.

npm — React / Next.js component (SteppieChatWidget)
CDN — single IIFE script (dist/widget.js / window.SteppieWidget)

Styles render inside Shadow DOM so host-page CSS does not collide.

Install (React / Next.js)

npm install @iffu/steppie-widget
# or: bun add @iffu/steppie-widget

Peer dependencies: react and react-dom (18 or 19).

React

import { SteppieChatWidget } from "@iffu/steppie-widget";

export function App() {
  return (
    <>
      {/* your app */}
      <SteppieChatWidget
        agentSlug="your-agent-slug"
        apiUrl="https://api.steppie.example"
      />
    </>
  );
}

Next.js (App Router)

Use a Client Component so the widget never runs during SSR:

// app/components/SteppieChatWidget.tsx
"use client";

import { SteppieChatWidget } from "@iffu/steppie-widget";

export function ChatWidget() {
  return (
    <SteppieChatWidget
      agentSlug="your-agent-slug"
      apiUrl="https://api.steppie.example"
    />
  );
}

// app/layout.tsx
import { ChatWidget } from "./components/SteppieChatWidget";

export default function RootLayout({ children }) {
  return (
    <html lang="en">
      <body>
        {children}
        <ChatWidget />
      </body>
    </html>
  );
}

CDN / HTML

After publishing to npm, load the IIFE from jsDelivr (or unpkg):

<script
  src="https://cdn.jsdelivr.net/npm/@iffu/steppie-widget@latest/dist/widget.js"
  data-agent="your-agent-slug"
  data-api-url="https://your-api.run.app"
  async
></script>

unpkg equivalent: https://unpkg.com/@iffu/steppie-widget@latest/dist/widget.js

Programmatic API after the script loads:

window.SteppieWidget.mount({
  agentSlug: "your-agent-slug",
  apiUrl: "https://api.steppie.example",
});

// later
window.SteppieWidget.unmount();

API

| Export | Description | | --- | --- | | SteppieChatWidget | React component (agentSlug, optional apiUrl) | | mountWidget / unmountWidget | Imperative mount helpers | | configureSteppie | Set defaults (e.g. apiUrl) before mount |

Local development

# from repo root
bun install
bun run --filter @iffu/steppie-widget dev

Build both the ESM package and the CDN IIFE:

bun run --filter @iffu/steppie-widget build
# → dist/index.js, dist/index.d.ts, dist/widget.js

Test a local build in another project (before npm publish)

Bun errors with DependencyLoop if the project already has a registry version ("@iffu/steppie-widget": "^0.1.1") and you bun add a folder path on top of it. Remove the registry entry first, then add the path:

# in the widget package — build so dist/ is fresh
cd /path/to/steppie/widget
bun run build

# in your consumer app (e.g. portfolio)
bun remove @iffu/steppie-widget
bun add /path/to/steppie/widget

Or edit package.json to the file path and install:

"@iffu/steppie-widget": "file:/path/to/steppie/widget"

bun install

Switch back to the published package later with bun add @iffu/steppie-widget@latest.

Deploy CDN (`widget.js`) on Vercel

Host the IIFE as a separate Vercel project (not the dashboard). Use Vercel’s *.vercel.app domain — no custom domain required.

Push this repo to GitHub (if it isn’t already).
In Vercel → Add New… → Project → import this repo.
Configure the project:
- Root Directory: widget
- Leave Framework / Build / Output alone — widget/vercel.json sets npm install, npm run build, and dist.
Deploy. Copy the production URL (e.g. https://steppie-widget-xxxx.vercel.app).
Confirm the script loads: open https://<project>.vercel.app/widget.js — you should see the IIFE bundle. In a browser console on any page that loads it, window.SteppieWidget should exist.
On the dashboard Vercel project (and in local dashboard/.env), set:
```
NEXT_PUBLIC_WIDGET_SCRIPT_URL=https://<project>.vercel.app/widget.js
```
Redeploy the dashboard so Agent Studio install snippets use that URL.

Each push to the branch connected to the widget project rebuilds and replaces /widget.js. Cache headers are short (max-age=60) so updates show up quickly without a custom domain/versioned path.

Publish (npm) + jsDelivr

Scoped package under your npm user (@iffu/...). Publish while logged in as iffu.

This repo is a Bun monorepo. Plain npm version patch then tries to reify npm workspaces and crashes (Cannot read properties of null (reading 'matches')). Use the helper scripts instead (they already bumped package.json to 0.1.2 if you hit that error once — check "version" before bumping again):

npm whoami   # must be: iffu
cd widget

# Bump package.json only (no git tag, no npm workspace reify)
bun run version:patch   # or version:minor

bun run build
npm pack --dry-run   # confirm dist/widget.js is included
npm publish --access public

Verify within a minute or two:

Registry: https://www.npmjs.com/package/@iffu/steppie-widget
jsDelivr: https://cdn.jsdelivr.net/npm/@iffu/steppie-widget@latest/dist/widget.js
unpkg: https://unpkg.com/@iffu/steppie-widget@latest/dist/widget.js

After publish, confirm the registry metadata exists (not just the npm website):

curl -sS 'https://registry.npmjs.org/@iffu%2fsteppie-widget' | head
# should be JSON with "versions", not {"error":"Not found"}

Agent Studio HTML/JS/Vue snippets default to jsDelivr @latest (no per-release snippet bump). Override with NEXT_PUBLIC_WIDGET_SCRIPT_URL if you prefer the Vercel CDN host instead. React/Next installs still use the npm package and need a dependency update to pick up new releases.

Snippet apiUrl / data-api-url use NEXT_PUBLIC_WIDGET_API_URL or NEXT_PUBLIC_API_URL when set.

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme