@usereq/widget

Single-package repository for widget runtime/shared exports and embed bundle.

What this package contains

• Core/shared TypeScript exports from root src.
• Embed browser IIFE bundle generated at root dist/widget.js.

This repo publishes one npm package: @usereq/widget (scoped; see package.json).

Repository layout

• src (core, shared, runtime, custom-element, embed entry)
• dist (built embed artifact; created by bun run build)
• tsconfig.json (global TS config)
• .env.example (optional local env template; not loaded automatically—copy to .env / .env.production as needed)

Prerequisites

• Bun 1.2+ (matches packageManager in package.json)
• npm CLI for publishing (npm whoami, npm publish)
• npm account with publish permission to the @usereq scope (or change the package name before publishing elsewhere)

Environment variables

These matter when you run bun run build (specifically the Vite embed step). Vite reads them from the repo root via .env, .env.local, .env.production, .env.production.local, and so on (see Vite env files). vite build uses mode production, so .env.production is the usual place for release API URLs.

| Variable | When set | Effect | | ---------------------------- | ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- | | USEREQ_WIDGET_DEV_API_BASE | Embed build | Highest-priority API origin (useful for dev-tag releases). If set, it overrides USEREQ_WIDGET_API_BASE. | | USEREQ_WIDGET_API_BASE | Embed build | Preferred API origin string inlined into dist/widget.js (no trailing slash normalization at build time; the runtime trims and strips trailing slashes). | | NEXT_PUBLIC_API_URL | Embed build | Used only if USEREQ_WIDGET_API_BASE is empty—handy if you already define this in a Next.js monorepo. | | (neither set) | Embed build | Falls back to http://localhost:3000 in the Vite config. |

Runtime globalThis (advanced): getWidgetApiBase() (see src/runtime/api-origin.ts) prefers the compile-time __USEREQ_WIDGET_API_BASE__ value when it is non-empty after trimming. The Vite embed build always defines that symbol to a non-empty string (see defaults above), so changing the API URL for the published dist/widget.js requires a rebuild with a different USEREQ_WIDGET_API_BASE. The globalThis.__USEREQ_WIDGET_API_BASE__ path mainly applies when consuming source from this package without inlining a base URL (for example your own bundler without that define). If nothing resolves, the function falls back to http://localhost:4000.

Example for a production embed build:

USEREQ_WIDGET_API_BASE=https://api.example.com bun run build

Or create .env.production in the repo root (gitignored by default; copy from .env.example).

Install

bun install

Development

Typecheck:

bun run typecheck

Build core + embed:

bun run build

Build individual targets:

bun run build:core
bun run build:embed

Build outputs

• Core/shared exports are served from root src.
• Embed bundle is emitted at root dist/widget.js (plus css artifact if emitted).

Usage

Core/shared exports

import { registerWidgetElement } from "@usereq/widget/register";
registerWidgetElement();

Embed bundle from same package

The package exports embed at subpath @usereq/widget/embed (maps to dist/widget.js).

For CDN/script usage, use:

• unpkg: https://unpkg.com/@usereq/widget/dist/widget.js
• jsDelivr: https://cdn.jsdelivr.net/npm/@usereq/widget/dist/widget.js

The embed entry automatically registers <usereq-agent-widget>.

Publish guide

Publish once from this repo root. The package is scoped (@usereq/widget); publishConfig.access is already public.

1) Login and verify permissions

npm whoami
# If needed:
npm login

Ensure you are logged in as a user or CI token that is allowed to publish under the @usereq scope on npm.

2) Bump version

Update version in root package.json only.

To publish under a different scope or unscoped name, change the name field and update import paths / CDN URLs in your own docs accordingly.

3) Set API base for production (recommended)

Set USEREQ_WIDGET_API_BASE (or .env.production) so the published dist/widget.js targets your production API. Skipping this bakes in the default from Vite (http://localhost:3000).

4) Clean build before publish

bun run typecheck
bun run build

Confirm dist/widget.js exists (the files field includes dist and src).

5) Sanity check contents (optional)

npm pack --dry-run

6) Publish

npm publish

--access public is optional here because package.json already sets publishConfig.access to public.

7) Verify

npm view @usereq/widget version

GitHub Actions

• CI (.github/workflows/ci.yml): runs on pull requests and on pushes to main / master — bun install --frozen-lockfile, bun run typecheck, bun run build.
• Publish (.github/workflows/publish.yml): runs when you push tags matching:
  • v* (for example v0.2.0) → publishes to npm default latest tag.
  • dev-v* (for example dev-v0.2.0-dev.1) → publishes to npm dev dist-tag. Configure repository secrets:
  • NPM_TOKEN (required): npm automation token able to publish @usereq/widget.
  • USEREQ_WIDGET_API_BASE (optional): production API base for normal v* releases.
  • USEREQ_WIDGET_DEV_API_BASE (optional): dev API base used by dev-v* releases.
  • For dev-v* publishes, keep package.json version unique (for example prerelease versions like 0.2.0-dev.1), because npm does not allow publishing the same version twice even with different dist-tags.

Notes

• No workspace dependency is required for this repo itself; published consumers still install @usereq/widget’s npm dependencies (for example @usereq/ui) like any other package.
• One package version controls both core/shared exports (src via exports) and the embed artifact (dist/widget.js).