dimah-formv0.6.1

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/react

Define a form

lib/forms/feedback.ts
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" },
    },
  ],
});
lib/forms/index.ts
import { feedbackForm } from "./feedback";

export const forms = {
  feedback: feedbackForm,
};

Create the instance

lib/form.ts
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

app/api/form/[...all]/route.ts
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

lib/form-client.ts
"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

components/questionnaire.tsx
"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

app/page.tsx
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

Continue

The complete implementation, including custom fields, scoring, SQL persistence, dataset export, and insights, is in the Next.js example.

On this page