One page, every platform. A single-release smart link: a big cover, buttons to every streaming service, and an artist admin to edit the release + links and see click counts. A real, buildable Hanzo app you fork on hanzo.app and deploy live on Hanzo Cloud.
- UI —
@hanzo/gui(the Hanzo design system) under Vite + React 19. No Tailwind, no second kit. - Auth —
@hanzo/iam, OAuth2 PKCE against hanzo.id. No local passwords — IAM owns every credential interaction. - Data —
@hanzo/base, the IAM-native, org-scoped data plane.releaseandlinksare real Base collections.
Fans see a clean, mobile-first page for the release; the artist signs in to edit it and watch the per-platform click counts.
| Package | Version |
|---|---|
react / react-dom |
^19.2.4 |
@hanzo/gui + @hanzogui/config |
7.3.0 |
@hanzo/iam |
^0.13.1 |
@hanzo/base |
^0.2.1 |
vite |
^6 (@vitejs/plugin-react) |
typescript |
5.9.3 |
npm install
npm run dev # http://localhost:5173
npm run build # tsc --noEmit && vite build -> dist/
npm run preview # serve the production build (SPA fallback on)Out of the box it runs against live Hanzo (hanzo.id + api.hanzo.ai) — no config needed. The public landing shows a demo release; sign in to edit your own.
Only VITE_-prefixed vars reach the browser (this is a static SPA — there is no
server). Defaults in parentheses.
| Var | Purpose |
|---|---|
VITE_HANZO_IAM_URL (https://hanzo.id) |
OIDC issuer. |
VITE_IAM_CLIENT_ID (hanzo-app) |
IAM application (<org>-<app>). Its redirect-URI list must allow this deploy's /auth/callback — see Ambient IAM. |
VITE_HANZO_REDIRECT_URI (${origin}/auth/callback) |
PKCE redirect. |
VITE_HANZO_BASE_URL (https://api.hanzo.ai) |
Browser-reachable Hanzo Base data plane. Deploy injects the provisioned URL. |
login() starts an OAuth2 PKCE S256 redirect to hanzo.id; hanzo.id returns
to /auth/callback, where handleCallback() exchanges the code for tokens
(stored in localStorage, refresh-aware via offline_access). Every deployed
app is a static site at <slug>.hanzo.app; there is no server token — the
SPA authenticates the user in the browser and carries the resulting IAM JWT to
Base.
The one deploy requirement: the IAM client (VITE_IAM_CLIENT_ID) must list this
origin's /auth/callback as an allowed redirect URI. Deploy provisions a
dedicated release-smartlink client (or use a
https://*.hanzo.app/auth/callback wildcard on the shared client).
schema.sql is the app's databaseSchema (SQL DDL). On publish,
Hanzo Cloud translates each CREATE TABLE into a Hanzo Base collection
(provisionBaseFromDDL, additive + idempotent). Base manages
id/created/updated/owner/org, stamps owner+org from the verified
IAM principal, and scopes every row to the caller's org (rule
@request.auth.org_id = org). At runtime src/views/admin.tsx and
src/views/smartlink.tsx read/write the release and links collections
through @hanzo/base/react (useQuery/useMutation) carrying the IAM token.
hanzo.yml declares a static build (npm run build → dist/,
served at <slug>.hanzo.app) plus the Base schema to provision and the env to
inject. Do not build a container image locally — Hanzo Cloud owns builds and
deploys. CI here only proves the template compiles green.
src/
main.tsx entry
providers.tsx GuiProvider -> IamProvider -> BaseProvider(client=IAM-token)
app.tsx route (/auth/callback) + auth gate
gui.config.ts createGui(defaultConfig from @hanzogui/config/v5)
iam.config.ts IAM PKCE config
env.ts the VITE_ env contract, one place
lib/base.ts BaseClient carrying the IAM bearer token
lib/catalog.ts domain: row shapes + streaming brand chips + cover palettes
auth/callback.tsx PKCE return leg
views/
smartlink.tsx the fan-facing smart link (presentational)
signed-out.tsx public landing (demo release) + artist sign-in
home.tsx signed-in shell: live preview + editor
admin.tsx edit release + links, see click counts (Base CRUD)
chip.tsx streaming brand mark
schema.sql databaseSchema (release, links) -> Base collections on publish
hanzo.yml Hanzo Cloud build/deploy manifest