Files

Ryth Azhur fe39fcb229 Restructure tree by role; rename mizan-runtime → mizan-base

packages/ flattens into:
  backends/   server protocol adapters (mizan-django, mizan-ts)
  frontends/  client kernel + framework adapters (mizan-base, mizan-react, mizan-vue, mizan-svelte)
  workers/    runtime workers (mizan-ssr)
  cores/      shared language-level primitives (empty for now; mizan-python forthcoming)

The frontend kernel (was packages/mizan-runtime, now frontends/mizan-base) is
renamed to reflect its role — it's the shared base that frontend adapters
depend on directly. Reflects the substrate position that per-framework adapters
wrap a single shared kernel; codegen targets the adapter, not the raw kernel.

Path updates landed in: Makefile, two Gitea workflows, Dockerfile.test, four
example/harness config files, .claude/settings.local.json, four docs
(CLAUDE/ISSUES/ROADMAP/AFI_ARCHITECTURE), four codegen templates (stage1 +
react/vue/svelte adapters), and three package.jsons (the mizan-base rename
plus mizan-vue/svelte peerDeps).

Generated files under examples/django-react-site/harness/src/api/ still
reference @mizan/runtime — left as-is; they're regenerated artifacts and
the harness is non-functional pending the React wrapper-layer codegen.

Also folded in a pre-existing fix: the Gitea workflows had
working-directory: react / django pointing at a layout that predates
packages/, never updated.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

2026-05-05 20:55:37 -04:00

2.4 KiB

Raw Blame History

@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.

1. Configure

// django.config.mjs
export default {
    source: {
        django: {
            managePath: '../backend/manage.py',
            command: ['uv', 'run', 'python'],
        },
    },
    output: 'src/api/generated.ts',
}

2. Generate

npx mizan-generate        # once
npx mizan-generate --watch # dev mode

3. Wrap your app

import { DjangoContext } from '@/api'

<DjangoContext>
    <App />
</DjangoContext>

DjangoContext 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

File	Contents
`generated.django.tsx`	`DjangoContext` + typed hooks
`generated.mizan.ts`	Pydantic types
`generated.forms.ts`	Form hooks with Zod
`generated.channels.hooks.tsx`	Channel hooks
`index.ts`	Re-exports everything

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

2.4 KiB Raw Blame History