tsup is gone. `pnpm build` is two tsc passes (ESM+types, then CJS with
--noCheck) plus scripts/postbuild.mjs, which resolves relative specifiers to
fully-specified paths, folds the CJS emit into dist as .cjs, and stamps
'use client' on every module.
Bundling a LIBRARY defeats the consumer's tree shaking: tsup's code splitting
emitted 11 shared chunk-*.js, so `import { Button } from '@hanzo/ui'` dragged
in chunk-RCMDRI6V.js (48K of source). Measured with esbuild against the packed
tarballs, that import costs 4717 bytes from 8.0.27 and 2021 from this build.
Output now mirrors src/ one-for-one — 220 .js, 220 .cjs, 220 .d.ts, 0 chunks —
so every exports subpath resolves by construction, with no entry list to drift.
rollup-plugin-dts (tsup's dts worker) was also the one thing that could not
run on TypeScript 7; declarations come from tsc, so pkg/ui builds on 7.0.2.
pkgs/canvas 0.2.2: it ships raw TS as its entry, so a consumer's compiler sees
its side-effect CSS import. Its css.d.ts was never loaded (nothing imports it);
index.ts now references it, which TS 7 requires (TS2882).
Verified on TS 7.0.2 against the pnpm-packed tarball: build exit 0, 181 tests
pass, all 24 exports subpaths (111 with primitives expanded) bundle under both
the import and require conditions, ESM + CJS load in Node, and a consumer
typechecks clean under moduleResolution bundler.
Co-authored-by: Hanzo Dev <[email protected]>
20 KiB
@hanzo/ui — LLM context
What this is. The React component library for AI applications: 161+
components, 24+ blocks, two themes, and a single typed import surface, all on ONE
substrate (@hanzo/gui) so the same import runs on web, native and desktop.
Published as @hanzo/ui (v8) on npm. Docs at https://ui.hanzo.ai. Dev port: 3003.
Canonical role. This is the canonical impl repo for Hanzo's web UI kit —
frontend components, not an SDK. It sits alongside the two SDK lines (full cloud
SDK generated from OpenAPI in hanzo-<lang>/sdk + wrapper in hanzoai/<lang>-sdk;
AI/agents lib hanzo in hanzoai/python-sdk flagship, @hanzo/ai in hanzo-js/ai).
@hanzo/event (telemetry, POST /v1/event) lives here in pkgs/event. DRY: one
impl, one place — link out, never duplicate.
Brand rules (hard).
- Never call Hanzo an "LLM gateway" or position it against LiteLLM — it is a full AI SDK / AI cloud, not a proxy. Purge that framing on sight.
- Paths are
/v1/…only — never an/api/prefix. - Zen models are our own family — never name upstream models.
- Voice: "Hanzo — the Open AI Cloud." Developer-first, crisp, no emoji-spam.
Install / run.
pnpm add @hanzo/ui # consume
# dev:
pnpm install && pnpm build:registry && pnpm dev # registry MUST build before app
Key entry points. pkg/ui/ (core lib + v8 subpaths: /product /data /canvas
/dashboard /usage /gitops) · app/registry/{default,new-york}/
(component SOURCE OF TRUTH) · pkgs/* (auto-published @hanzo/* packages) ·
packages/shadcn/ (CLI) · app/content/docs/ (MDX docs). Publish = bump a
package version + merge to main (.github/workflows/publish.yml).
Spec / more context. Canonical SDK + docs model: ~/work/hanzo/SDK-ARCHITECTURE.md.
Detailed engineering notes (build order, import surface, telemetry, upstream sync,
gotchas) follow below.
v8 — the canonical @hanzo/ui (pkg/ui)
@hanzo/ui@8 (pkg/ui) is THE Hanzo component library, and there is ONE
substrate: every component renders through @hanzo/gui (Tamagui) primitives on
the @hanzo/tokens scale, so one import works on web, native (expo) and desktop
(Tauri). The Radix + Tailwind surface it used to ship alongside is gone — it
lives on as its own package, @hanzo/shadcn, and @hanzo/ui no longer depends
on it, on any @radix-ui/* package, on cva, cmdk or sonner.
@hanzo/ui-shadcn (pkgs/ui, v5.x) is the legacy standalone package —
superseded, being retired.
Layout
pkg/ui/src/
core/ design core: cn.ts (clsx+tailwind-merge),
tokens.ts (re-export of @hanzo/tokens), fonts.ts (Geist vars)
theme.css SELF-CONTAINED token CSS vars + Geist Sans/Mono — the identity
backends/gui/ THE component surface on @hanzo/gui. index.ts is its manifest.
product/ the product/app layer (charts, PageHeader, ComboBox, …)
models/ the unified ModelSelector + catalog helpers
primitives/ GENERATED per-member entrypoints (scripts/gen-primitives.mjs)
index.ts root barrel = the component surface + cn
House rules for a component
- Style through gui props and theme tokens (
$background,$color12,$borderColor) — never a utility class string, never a hard-coded font. - Touch targets meet the 44px floor via
hitSlop, never via padding. - Behaviour (focus, portalling, keyboard, a11y) comes from the matching
@hanzogui/*primitive; nothing reimplements it. - Free-form text children go through
ink();data-slotmarkers throughslot(). One helper each, one place. - Module scope stays side-effect free —
forwardRef/createContextcalls carry/* @__PURE__ */and nothing assignsdisplayName, so importing one symbol never drags a neighbour in. A one-symbol import bundles ~4.7KB against ~29KB for the whole barrel.
Subpaths
| Subpath | What |
|---|---|
@hanzo/ui |
the component API: Button, Badge, Card*, Checkbox, Dialog*, DropdownMenu*, Input, Toaster, Avatar*, Tabs*, Select*, Tooltip*, Popover*, Command*, Collapsible*, Resizable*, ScrollArea, Slider, Switch, Progress, Separator, Label, Textarea, AspectRatio — + cn (the product layer is kept off root, at /product) |
@hanzo/ui/components |
alias of the root surface, for hosts that shim the package through a declare module |
@hanzo/ui/product |
the product/app layer: charts, metrics, PageHeader, StatusTag, EmptyState, ComboBox, SlideOver, Toast, Reorder, Field |
@hanzo/ui/models |
ModelSelector + fetchModelCatalog + catalog helpers |
@hanzo/ui/core · /tokens |
cn, Geist font vars, the @hanzo/tokens color/theme/radii/spacing scale |
@hanzo/ui/theme.css |
the self-contained Hanzo identity stylesheet |
@hanzo/ui/primitives/<Member> |
per-member entrypoints (for hosts that modularize @hanzo/ui imports) |
@hanzo/ui/data |
@hanzo/data: RecordsView, DataTable, typed field editors |
@hanzo/ui/{canvas,dashboard,usage,gitops} |
the optional-peer kits (each re-exports its home package) |
Everything ships COMPILED from dist — every exports target is a real file in
the tarball, including theme.css and all 90 primitives/* entrypoints.
One DropdownMenu
There is one DropdownMenu, with one API. It is the compound surface (Trigger,
Content, Item, CheckboxItem, RadioItem, Label, Separator, Shortcut, Group,
Portal, Sub*, RadioGroup) AND it accepts the declarative trigger + items
spec, which it renders through those very same parts. @hanzo/ui and
@hanzo/ui/product export the same component; there is no second shape.
modularizeImports support
scripts/gen-primitives.mjs reads the gui backend barrel and emits one
src/primitives/<Member>.tsx per exported value (re-export from the backend).
This makes @hanzo/ui/primitives/Button etc. resolve, so a host whose
next.config rewrites @hanzo/ui → @hanzo/ui/primitives/{{member}} works
unchanged. Re-run pnpm gen:primitives after changing the surface.
Build — plain tsc, one file in, one file out
There is no bundler. pnpm build is two tsc passes plus scripts/postbuild.mjs:
| Pass | Config | Emits |
|---|---|---|
| ESM + types | tsconfig.build.json |
dist/**/*.js, .d.ts, .js.map, .d.ts.map |
| CJS | tsconfig.cjs.json (--noCheck) |
dist-cjs/**/*.js, folded into dist/**/*.cjs |
postbuild.mjs does the only two things tsc will not: it resolves every
relative specifier to a fully-specified path (./button → ./button.js,
./x → ./x/index.js; .cjs on the CJS half) so Node ESM and strict bundlers
resolve, and it prepends 'use client' to every emitted module — the whole
library is client-side @hanzo/gui UI and Next's flight-client loader wants the
directive first. It is prepended without a newline so source-map lines hold.
The output is UNBUNDLED and mirrors src/ one-for-one, so a consumer importing
one symbol pulls one module. A bundler here would be actively harmful: tsup's
code splitting emitted 11 shared chunk-*.js, and importing Button alone
dragged in chunk-RCMDRI6V.js (48K of source). Measured with esbuild, import { Button } from '@hanzo/ui' costs 4717 bytes bundled from tsup output vs 2021
from tsc output. Dropping rollup-plugin-dts (tsup's dts worker) is also
what makes the package build on TypeScript 7, which it cannot do otherwise.
Everything under src/ is emitted, so every exports subpath resolves by
construction — no hand-maintained entry list to drift.
NOTE: pkg/ui (singular) sits OUTSIDE the pkgs/* pnpm workspace, installs
standalone, and publishes via the maintainer flow, not publish.yml. Because the
optional-peer kits (canvas/dashboard/gitops/usage) are not on the public
registry, a standalone install must skip auto-installing peers. .npmrc and
pnpm-lock.yaml are gitignored here, so create the .npmrc once:
cd pkg/ui
printf 'auto-install-peers=false\nstrict-peer-dependencies=false\n' > .npmrc
pnpm install --ignore-workspace # component-surface deps (radix, cmdk, sonner, …) + @hanzo/tokens
pnpm gen:primitives # refresh the per-member entrypoints
pnpm typecheck:ui # scoped typecheck of the component surface (green)
@hanzo/tokens (pkgs/tokens) must be built first (pnpm --filter @hanzo/tokens build)
so the file: link resolves. The scoped typecheck:ui excludes the optional-peer
subpaths, whose homes aren't installed standalone.
The kits = canvas, wallet, network, billing, dashboard, usage, gitops, data.
Add one by mirroring src/gitops.ts (a one-line export *) + a ./name export
- an optional peer/devDep.
pkg/*is a pnpm workspace member (forworkspace:*dev links), butpkg/uipublishes via the maintainer flow, notpublish.yml(which auto-publishes onlypkgs/*on a version bump — see PUBLISH_GUIDE.md). The shared shell lives here too:AppHeader+BrandMark(@hanzo/logo) +OrgSwitcher+orgScope(the console org-scope contract, hoisted per #36). Lux surfaces use@luxfi/web3for wallet/login;@hanzo/ui/wallet+/networkare the Hanzo-branded equivalents.
Repository Structure
ui/
app/ Hanzo documentation site (Next.js 15.3.1, React 19)
registry/ Component registry (SOURCE OF TRUTH)
default/ui/ 150+ components
default/example/ Usage demos
default/blocks/ 24+ full-page sections
new-york/ Alternative theme
content/docs/ MDX documentation
scripts/ Build scripts
apps/
v4/ Upstream shadcn v4 docs/registry app (port 4000)
packages/
shadcn/ shadcn CLI v4.1.0 (font system, chart colors, scaffold)
tests/ Integration tests for shadcn CLI
og/ OG image generation (Hanzo-only)
pkg/
ui/ Core library (npm)
react/ React primitives
brand/ Branding system
commerce/ E-commerce components
checkout/ Checkout flow
shop/ Shop components
agent-ui/ AI agent UI components
tokens/ Design tokens
skills/
shadcn/ AI skill definitions for shadcn CLI
templates/ Project templates (next, vite, astro, react-router, start + monorepo variants)
template/next/ Hanzo-customized Next.js template
Critical: Build Order
Registry MUST build before app. The registry generates JSON that the CLI reads.
pnpm build:registry # MUST run first
pnpm build # Then build app
Commands
pnpm dev # Dev server (:3003)
pnpm build:registry # Build component registry
pnpm build # Build app
pnpm lint # Lint all workspaces
pnpm typecheck # Type checking
pnpm test # Unit tests
pnpm test:e2e # Playwright E2E
How this ships
One way, and it runs on our own stack:
push -> github.com/hanzoai/ui (a mirror)
.github/workflows/sync.yml carries refs onward
-> git.hanzo.ai/hanzoai/ui CANONICAL
.hanzo/workflows/ci.yml lint, typecheck, build, test
.hanzo/workflows/registries.yml the v4 registry check
.hanzo/workflows/publish.yml publishes every pkgs/* package
.hanzo/workflows/deploy.yml builds ghcr.io/hanzoai/ui
-> hanzoai/universe crs/ui.yaml names the tag that is live
-> hanzoai/operator reconciles the App
-> hanzoai/static behind hanzoai/ingress serves ui.hanzo.ai
git.hanzo.ai is canonical; GitHub is a mirror. .github/workflows/ holds
exactly one file, sync.yml, and its only job is getting refs to the forge. Every
build, check, publish and deploy is a workflow under .hanzo/workflows/, which the
forge reads. .hanzo/workflows uses GitHub Actions syntax, so a workflow moves
between the two by changing directory and nothing else.
No Vercel. ci.yml used to end in a deploy-preview job that ran vercel deploy
on every PR; previews come from our own stack or not at all, so that job is gone.
Its status job never depended on it.
Publishing
One way: bump a package's version in its package.json and merge to main.
.hanzo/workflows/publish.yml detects the changed @hanzo/* package and publishes
it to npm (needs NPM_TOKEN as a forge secret). No changesets, no version-PR bot
— the semver bump is the trigger.
It is the SOLE publisher of every non-private @hanzo/* in pkgs/*, and it
mirrors the same tarball to api.hanzo.ai/v1/packages/hanzo/npm when
HANZO_REGISTRY_TOKEN is present. That mirror is best-effort by construction: no
token means a notice, not a failure, and npmjs stays authoritative either way.
Deploying the site
app/ is a Next.js static export (output: "export", trailingSlash: true);
pnpm build there writes app/out, which Dockerfile copies into
ghcr.io/hanzoai/static. ui.hanzo.ai has been served that way since 2026-07-25 —
no Cloudflare, no GitHub Pages.
What was missing until now is the build. crs/ui.yaml is live and promoted, but no
workflow ever produced the image it pins: every tag up to v5.7.6 was pushed by
hand. .hanzo/workflows/deploy.yml is that step. It publishes
ghcr.io/hanzoai/ui:<sha> and stops there — a build never deploys itself. A human
sets spec.image.tag in hanzoai/universe
infra/k8s/operator/crs/ui.yaml, which is the one live thing that says which build
serves.
Coverage lives in ci.yml's test job, which runs pnpm test:coverage so the
lcov it uploads to Codecov actually exists. A separate coverage.yml used to run
the same suite a second time for the same upload plus a PR comment through the
GitHub API; one workflow does it now.
registries.yml keeps the apps/v4 registry honest: reserved namespaces are
rejected and pnpm --filter=v4 validate:registries must pass. Its other job
labelled and commented on pull requests with the gh CLI against the GitHub API,
which does not exist on the forge, so that job did not come along.
Telemetry — @hanzo/event is the ONE client (pkgs/event)
@hanzo/event is the single canonical telemetry client for every Hanzo surface.
ONE API surface over TWO planes — the client never sends the org; the server
resolves the tenant.
- Event stream — pageview/event/identify/group (and an error breadcrumb),
batched to
POST {host}/v1/eventwith{ batch: [Event, …] }-> { accepted, dropped }. Tenant from the session or a publishablepk_key. - Error plane — every captured exception is ALSO framed as a real Sentry
envelope and POSTed to
POST {dsn.origin}/v1/sentry/{projectId}/envelope/?sentry_key=…. This is the ONLY thing that reaches the Sentry error dashboard.
There is NO server-side fan-out from
/v1/eventinto Sentry. Versions ≤ 0.3.1 claimed there was ("lensed server-side into … error tracking"). There is not: cloud's handler folds the exception intoproperties.$exception, writes one row to the event warehouse (readable viaGET /v1/errors), and stops. Because every property believed that claim, the whole fleet reported zero errors to Sentry until 0.3.2 added the envelope. Do not re-collapse these planes.
Configure the error plane with dsn (or NEXT_PUBLIC_HANZO_EVENT_DSN), minted
per property via POST /v1/sentry/projects. The DSN key is publishable and
write-only — safe in a bundle, same trust class as pk_. No DSN => the error
plane is inert (fail-safe: nothing sent, nothing thrown, event stream
unaffected); assert client.errorPlaneEnabled if you need to know.
Note that web analytics is a THIRD, separate plane and is NOT this client — it is
the analytics.hanzo.ai/hz.js tag, which speaks a different wire (a bare JSON
array of {site, ts, type, …}). analytics.hanzo.ai/v1/event and
api.hanzo.ai/v1/event share a path spelling but are different protocols; point
this client at the API host, never the analytics host.
Entries: . (framework-agnostic: createAnalytics, EVENTS, GOALS,
attribution + DSN/scrub helpers) and ./react (AnalyticsProvider,
useAnalytics, usePageview, ErrorBoundary). Auto error capture
(window.onerror / unhandledrejection / React boundary) makes it the drop-in
error-tracking replacement. Secrets and PII are scrubbed client-side before an
error leaves the device. SSR-safe, fail-soft, beacon-on-unload.
Build is a tsup dual bundle: CJS → .cjs, ESM → .mjs (required under
"type": "module" — a CJS .js is parsed as ESM and crashes require() with
"exports is not defined"). Each exports condition carries its own types.
One way — supersessions (no divergent telemetry client)
| Package | Status | Note |
|---|---|---|
@hanzo/event |
canonical | pkgs/event, posts /v1/event only |
@hanzo/capture (npm) |
deprecated → @hanzo/event |
the old name of this package; @hanzo/event is a superset |
pkgs/capture (@hanzo/[email protected] dup) |
deleted | stale in-repo duplicate, removed |
hanzoai/analytics packages/event (@hanzo/[email protected]) |
deleted | An unpublished FORK of this package in another repo. It was the only copy that could actually reach Sentry, while the published one here could not — the fleet's error telemetry died in that gap. Its envelope + scrub implementation was merged here in 0.3.2. Never fork this package again; it publishes from pkgs/event only. |
Three-Layer Architecture
- Components (
registry/{style}/ui/) — single primitives (Button, Card, Dialog). CLI-installable. - Examples (
registry/{style}/example/) — usage demos for docs via<ComponentPreview />. - Blocks (
registry/{style}/blocks/) — full-page sections (Dashboard, Login). NOT CLI-installable, docs only.
Import Path Transformation
Registry files use @/registry/default/ui/button. After CLI install, rewritten to @/components/ui/button.
Package Exports
import { Button, Card } from '@hanzo/ui'
import { Button } from '@hanzo/ui/components'
import * as Dialog from '@hanzo/ui/primitives/dialog'
import { cn } from '@hanzo/ui/lib/utils'
Adding a Component
- Create in BOTH themes:
app/registry/{default,new-york}/ui/my-component.tsx - Create example:
app/registry/default/example/my-component-demo.tsx - Create docs:
app/content/docs/components/my-component.mdx - Update nav:
app/config/docs.ts - Build:
pnpm build:registry
Tech Stack
React 19, Next.js 15.3+, Tailwind CSS 4 (OKLCH colors), Radix UI, Turborepo + pnpm, Fumadocs (MDX), class-variance-authority.
Upstream Sync
Remote shadcn points to a local clone of shadcn-ui/ui.
hanzoai/ui is NOT a GitHub fork — no shared object store, so large merges can fail on push.
Strategy: file-level checkout from shadcn/main for specific directories (not git merge).
- Take theirs: packages/shadcn/, packages/tests/, apps/, templates/, scripts/, skills/
- Keep ours: app/, pkg/, demo/, docs/, template/next/, pnpm-workspace.yaml, package.json
- Regenerate: pnpm-lock.yaml after sync
Key Features
- Page Builder (
/builder): drag-drop block assembly with @dnd-kit, export to TSX - White-Label: Zoo/Lux forks via
brands/{BRAND}.brand.ts - External Registries: 35+ sources in
app/registries.json, install vianpx @hanzo/ui add @aceternity/spotlight
Gotchas
- Registry index is
Index[style][name], NOTIndex[name]— caused silent block render failures - Shiki
getHighlighterincompatible with static export — replaced with basic pre/code - Some blocks (login-01, login-02, sidebar-02) have Server Component issues with event handlers
@hanzo/authv2.6.0 uses a pluggable provider registry:registerAuthProvider('firebase', FirebaseAuthService)
Rules
- Always build registry before app
- Keep default and new-york themes in sync
- Blocks are docs only, not CLI-installable
- Use pnpm, not npm/yarn
- Never commit symlinked files (AGENTS.md, CLAUDE.md, etc.)
- Documentation goes in
app/content/docs/, not random root MD files