Ryth Azhur
fe39fcb229
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>
104 lines
2.4 KiB
Markdown
104 lines
2.4 KiB
Markdown
# @rythazhur/mizan (TypeScript)
|
|
|
|
React client for the mizan framework. See the [monorepo root](../README.md) for full documentation.
|
|
|
|
## Install
|
|
|
|
```bash
|
|
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
|
|
|
|
```js
|
|
// django.config.mjs
|
|
export default {
|
|
source: {
|
|
django: {
|
|
managePath: '../backend/manage.py',
|
|
command: ['uv', 'run', 'python'],
|
|
},
|
|
},
|
|
output: 'src/api/generated.ts',
|
|
}
|
|
```
|
|
|
|
### 2. Generate
|
|
|
|
```bash
|
|
npx mizan-generate # once
|
|
npx mizan-generate --watch # dev mode
|
|
```
|
|
|
|
### 3. Wrap your app
|
|
|
|
```tsx
|
|
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
|
|
|
|
```tsx
|
|
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
|
|
|
|
```bash
|
|
# Unit tests (Vitest, jsdom)
|
|
npm test
|
|
|
|
# E2E tests (Playwright, real browser)
|
|
# Requires Docker backend running
|
|
npx playwright test
|
|
```
|