Quickstart
Define a form, mount the handler, and render a fill session in Next.js.
A fill session in the Next.js App Router — drafts, showWhen, and snapshot validation.
Install
npm i @dimah-form/server @dimah-form/reactDefine a form
import { defineForm } from "@dimah-form/server";
export const feedbackForm = defineForm({
title: "Product Feedback",
slug: "feedback",
fields: [
{ id: "fullName", type: "text", label: "Full name", required: true },
{
id: "rating",
type: "select",
label: "Rating",
required: true,
options: [
{ value: "great", label: "Great" },
{ value: "ok", label: "Okay" },
{ value: "poor", label: "Poor" },
],
},
{
id: "improvements",
type: "text",
label: "What could we improve?",
required: true,
showWhen: { field: "rating", equals: "poor" },
},
],
});import { feedbackForm } from "./feedback";
export const forms = {
feedback: feedbackForm,
};Create the instance
import { dimahForm, memoryAdapter } from "@dimah-form/server";
import { forms } from "@/lib/forms";
export const form = dimahForm({
database: memoryAdapter(),
forms,
basePath: "/api/form",
});
export type Form = typeof form;memoryAdapter() is process-local. For SQL, see Persistence.
Mount the handler
import { toNextJsHandler } from "@dimah-form/server/next";
import { form } from "@/lib/form";
export const { GET, POST, PUT, PATCH, DELETE } = toNextJsHandler(form);Other runtimes: Integration.
Create the client
"use client";
import { createFormClient } from "@dimah-form/react";
import type { Form } from "@/lib/form";
export const formClient = createFormClient<Form>({
basePath: "/api/form",
});
export const { useFormResponse } = formClient;Render the fill UI
"use client";
import { emptyToNull, fieldLabel, fieldOptions } from "@dimah-form/react";
import type { FormSnapshot } from "@dimah-form/react";
import { useFormResponse } from "@/lib/form-client";
export function Questionnaire({ form }: { form: FormSnapshot }) {
const q = useFormResponse<"feedback">({
snapshot: form,
autosave: { debounceMs: 1000 },
});
if (q.inactive) return <p>This form is inactive.</p>;
if (q.status === "submitted") return <p>Submitted.</p>;
return (
<form
onSubmit={(event) => {
event.preventDefault();
void q.submit();
}}
>
<h1>{form.title}</h1>
{q.visibleFields.map((field) => {
const binding = q.field(field.id);
const value = typeof binding.value === "string" ? binding.value : "";
return (
<label key={field.id}>
{fieldLabel(field)}
{field.type === "select" ? (
<select
value={value}
disabled={binding.disabled}
onChange={(event) =>
binding.onChange(emptyToNull(event.target.value))
}
>
<option value="">Select…</option>
{fieldOptions(field).map((option) => (
<option key={option.value} value={option.value}>
{option.label}
</option>
))}
</select>
) : (
<input
value={value}
disabled={binding.disabled}
onChange={(event) =>
binding.onChange(emptyToNull(event.target.value))
}
/>
)}
{binding.error ? <span>{binding.error}</span> : null}
</label>
);
})}
<button type="submit" disabled={q.pending !== undefined || q.locked}>
{q.pending === "submit" ? "Submitting…" : "Submit"}
</button>
</form>
);
}For a shadcn layout, use FormView instead of this markup.
useFormResponse starts the response lazily on the first draft write, submit,
or abandon call. Pass an existing response when the server has already
started or resumed the row.
Load the snapshot
import { Questionnaire } from "@/components/questionnaire";
import { form } from "@/lib/form";
export default async function Page() {
const snapshot = await form.api.getForm({
query: { formId: "feedback" },
});
return <Questionnaire form={snapshot} />;
}form.api runs in process. It does not call your HTTP route. A missing id throws UNKNOWN_FORM — it does not return null.
Frequently asked questions
Throw from guard. Stamp the owner in onStart so the client cannot pick respondentId:
import { APIError, FORM_ERROR_CODES, dimahForm } from "@dimah-form/server";
export const form = dimahForm({
// ...
guard: async ({ request }) => {
const session = await getSession(request);
if (!session) {
throw APIError.from("UNAUTHORIZED", FORM_ERROR_CODES.UNAUTHORIZED);
}
},
hooks: {
onStart: async ({ request, response }) => {
const session = await getSession(request);
response.respondentId = session.user.id;
},
},
});See Security.
Replace memoryAdapter() with db() from @dimah-form/db. See
Persistence.
For an authenticated flow, start or resume on the server with the respondent id
from the trusted session, then pass that row into the client session. Do not let
the browser choose another user's respondentId.
import { headers } from "next/headers";
import { Questionnaire } from "@/components/questionnaire";
import { form } from "@/lib/form";
export default async function Page() {
const session = await requireSession();
const response = await form.api.startResponse({
body: {
formId: "feedback",
respondentId: session.user.id,
resume: true,
},
headers: await headers(),
});
return <Questionnaire form={response.definition} response={response} />;
}import type { FormSnapshot, ResponseRecord } from "@dimah-form/react";
import { useFormResponse } from "@/lib/form-client";
export function Questionnaire({
form,
response,
}: {
form: FormSnapshot;
response: ResponseRecord;
}) {
const q = useFormResponse<"feedback">({ snapshot: form, response });
// Render the same fields and actions as above.
}For anonymous flows, respondentId can instead be an app-issued opaque resume
token. Authorization details: Security.
Continue
The complete implementation, including custom fields, scoring, SQL persistence, dataset export, and insights, is in the Next.js example.