Skip to content

CLAUDE.md

Latest commit

 

History

History
50 lines (33 loc) · 2.71 KB

CLAUDE.md

File metadata and controls

50 lines (33 loc) · 2.71 KB
Raw

zooza-widgets-module

Monorepo for @zooza/* npm packages — embeddable Zooza widgets wrapped for every major JS framework.

Project prefix

ZWM (for spec_id generation — ZOO is taken by zooza-api).

Architecture rule

@zooza/widgets-core owns 100% of DOM/loader logic. Framework packages (wc, react, vue, svelte) are thin lifecycle adapters — they never touch the embed mechanism directly. Any change to the embed contract goes into core only.

The embed contract mirrors the official snippet from api.zooza.app:

  1. data-zooza-api-url attribute on <body> — page-global, one API base per page
  2. embedder <script> whose id IS the company API key (public, per-company, required); data-version, data-widget-id attributes (data-widget-id is the constant "zooza")
  3. async widget script {apiUrl}/widgets/{version}/?type={type}&ref={ref} inserted before embedder — the key is never in the URL; the remote script reads it from the embedder's id in the DOM

Widget type → version map lives in packages/core/src/index.ts (WIDGET_VERSIONS).

API regions: https://api.zooza.app (default), https://{region}.api.zooza.app (uk, asia, open-ended for future). regionApiUrl() in core; explicit apiUrl beats region.

Config precedence everywhere: per-widget option/prop/attribute → initZooza() global config → default.

Commands

pnpm install --filter "@zooza/*"   # install package deps only (examples are heavy)
pnpm build                          # build all @zooza/* packages (tsup)
pnpm changeset                      # start a release note
pnpm release                        # build + publish (owner only)

Structure

  • packages/{core,wc,react,vue,svelte} — published packages, each: src/index.ts, tsup.config.ts, README.md
  • examples/{vanilla-html,react-vite,nextjs,vue-vite,svelte-vite} — runnable demos, workspace members, never published
  • assets/ — logo source; the inline SVG used at runtime lives in packages/core/src/logo.ts
  • specs/, handoffs/ — SDD lifecycle folders (see global CLAUDE.md)

Conventions

  • Framework deps are peerDependencies, never bundled; @zooza/widgets-core is a regular dependency (workspace:^)
  • All packages ship ESM + CJS + d.ts via tsup; exports maps with per-condition types
  • ref option is renamed refUrl in React/Vue (reserved prop) — keep names consistent otherwise
  • Versions are changeset-linked across all @zooza/* packages
  • The remote widget script renders the UI — packages must never reimplement widget UI

Cross-project

Widget script endpoint (/widgets/v1/, /widgets/v2/) is owned by zooza-api. Changes to the embed contract (e.g. a stable mount API) require a handoff to zooza-api.