@rythazhur/mizan (TypeScript)

React client for the mizan framework. See the monorepo root for full documentation.

Install

npm install @rythazhur/mizan@git+https://git.impactsoundworks.com/isw/mizan.git#workspace=react

Usage

You don't use this package directly. You use the generated hooks.

This is the pre-kernel React adapter: it ships its own MizanProvider (src/context.tsx) that owns HTTP/WebSocket/CSRF/session/context state directly, rather than subscribing to the @mizan/base kernel. It is still the provider the Django + desktop example wires against. (DjangoContext, useDjango, etc. are deprecated aliases for the Mizan* names.)

1. Configure

# mizan.toml
output = "src/api"
targets = ["react"]

[source.django]
manage_path = "../backend/manage.py"
command = ["uv", "run", "python"]

2. Generate

The codegen is the mizan-generate Rust binary (source at protocol/mizan-codegen/; protocol/mizan-generate/ is the npm launcher):

mizan-generate --config mizan.toml

3. Wrap your app

import { MizanProvider } from '@rythazhur/mizan'

<MizanProvider>
    <App />
</MizanProvider>

MizanProvider is the only provider you need. It handles HTTP, WebSocket, CSRF, session init, context auto-fetching, and channel connections.

4. Use generated hooks

import { useCurrentUser, useEcho, useContactForm, useChatChannel } from '@/api'

// Context (SSR-hydrated, auto-refreshed)
const user = useCurrentUser()

// Server function
const echo = useEcho()
const result = await echo({ text: 'hello' })

// Form (Zod + server validation)
const form = useContactForm()
form.set('email', 'test@example.com')
await form.submit()

// Channel (WebSocket)
const chat = useChatChannel({ room: 'general' })
chat.send({ text: 'hello' })
chat.messages  // typed, reactive

Generated Files

The Rust codegen emits per-target files into the configured output directory (Stage 1 is auto-included whenever react is a target):

File	Contents
`types.ts`	Pydantic types
`contexts/<name>.ts`	Per-context `fetchXxx` bundles
`react.tsx`	`<MizanContext>` provider + typed `use{Hook}()` hooks
`channels.ts` / `channels.hooks.tsx`	Channel types + hooks (when the schema carries channels)
`index.ts`	Stage 1 re-export root

Sub-exports

Import	When to use
`@rythazhur/mizan`	Core: `MizanProvider`, hooks, forms, errors
`@rythazhur/mizan/channels`	WebSocket channels
`@rythazhur/mizan/jwt`	JWT token management
`@rythazhur/mizan/client`	HTTP clients (CSR/SSR)
`@rythazhur/mizan/allauth`	Allauth UI components

These are library internals used by the generated code. You should import from @/api (your generated index), not from the library directly.

Running Tests

# Unit tests (Vitest, jsdom)
npm test

# E2E tests (Playwright, real browser)
# Requires Docker backend running
npx playwright test