# dimah-form

> Backend-first questionnaire engine: the library owns the protocol, definition snapshots, and submit validation. You own UI, auth, and the database adapter. Not a form renderer, and not a hosted survey product.

TypeScript packages: `@dimah-form/server` (`dimahForm()` handler and `api`), `@dimah-form/react` (thin client and `useFormResponse`). Optional `@dimah-form/db` is the FumaDB SQL adapter. Protocol types live in `@dimah-form/core`. There is no UI package.

HTTP adapters: Next.js App Router, Express, Hono, Fastify, Elysia, SvelteKit, and Node. Persistence is required: `memoryAdapter()` from `@dimah-form/server` (Quickstart), or optional `db()` from `@dimah-form/db` for SQL. Built-in field types: text, number, boolean, select, multiSelect, email, date. Extra types are `defineFieldType` validators, not components.

Use it when the app needs typed questionnaires with drafts, snapshots, and submit validation, while keeping widgets in the consumer app. Skip it when you want a ready-made form renderer, visual form builder, or hosted survey SaaS.

Install: `pnpm add @dimah-form/server @dimah-form/react`. Add `@dimah-form/db` only for production SQL.

- Auth stays in consumer `guard` hooks. Do not look for library auth.
- Persistence is `database`, not a plugin. Plugins add endpoints, hooks, field types, and error codes.
- Apps import from the package they already use: `@dimah-form/server` on the server, `@dimah-form/react` in the browser. Share `$Infer` with `export type Form = typeof form` and `createFormClient<Form>()`.
- Filling a response is headless: `useFormResponse` / `createFormResponseSession`. Consumers own widgets.
- Each response stores the definition it was started with. Submit validates that snapshot.

## Docs

- [Introduction](https://form.dimah.dev/docs.md): A headless questionnaire engine. You own the UI. The library owns snapshots, drafts, and submit validation.
- [Quickstart](https://form.dimah.dev/docs/quickstart.md): Define a form, mount the handler, and render a fill session in Next.js App Router.
- [Architecture](https://form.dimah.dev/docs/architecture.md): Package boundaries, data flow, and the six-stage request pipeline.
- [Snapshots](https://form.dimah.dev/docs/snapshots.md): Frozen definitions, response status, and compare-and-swap drafts.
- [Forms](https://form.dimah.dev/docs/forms.md): Author questionnaires with defineForm, field rules, showWhen, and $Infer.
- [React Client](https://form.dimah.dev/docs/react.md): useFormResponse — visibility, drafts, validation timing, and submit.
- [Widgets](https://form.dimah.dev/docs/widgets.md): Bind FormFieldBinding to your inputs, build a type dispatcher, and split long forms into steps.
- [Server](https://form.dimah.dev/docs/server.md): Create dimahForm(), mount HTTP adapters, and call form.api without a round trip.
- [Database](https://form.dimah.dev/docs/database.md): Persistence is required. A SQL database is not.
- [Auth](https://form.dimah.dev/docs/auth.md): Guard every operation in your app. Use on* / after* hooks to stamp ownership and run side effects.
- [Custom Fields](https://form.dimah.dev/docs/custom-fields.md): Add a server validator with defineFieldType. The UI widget stays in your app.
- [Plugins](https://form.dimah.dev/docs/plugins.md): Add endpoints, hooks, error codes, field types, and matching client methods.
- [Configuration](https://form.dimah.dev/docs/configuration.md): Options for dimahForm(), createFormClient(), useFormResponse, and ResponseStore.
- [Field Types](https://form.dimah.dev/docs/field-types.md): Built-in types, validation constraints, showWhen operators, and $Infer mappings.
- [Protocol](https://form.dimah.dev/docs/protocol.md): REST routes, client methods, form.api calls, and request payloads.
- [Errors](https://form.dimah.dev/docs/errors.md): Stable error codes, field issues, and helpers for mapping them in the UI.

## Packages

- [@dimah-form/server](https://www.npmjs.com/package/@dimah-form/server): `dimahForm()` — HTTP handler, typed api, adapters
- [@dimah-form/react](https://www.npmjs.com/package/@dimah-form/react): thin React client (`createFormClient` / `useFormResponse`)
- [@dimah-form/core](https://www.npmjs.com/package/@dimah-form/core): protocol SSOT, field types, fetch client
- [@dimah-form/db](https://www.npmjs.com/package/@dimah-form/db): optional FumaDB adapter for production SQL

## Optional

- [Full docs dump](https://form.dimah.dev/llms-full.txt): every page as markdown
- [GitHub](https://github.com/dimah-kz/dimah-form): source and the example app
- [X](https://x.com/dimahkzx): updates