@k8ordo/form

はじめる

登壇の申し込みフォームを例に、zodのスキーマを1つ書き、入力欄の属性とサーバーでの検証をそこから作ります。

このページの内容

インストール

bash
npm install @k8ordo/form zod

次の環境で動きます。

  • React 19.3以上
  • TypeScriptで書くなら、TypeScript 7以上

エージェント向けのガイドはnode_modules/@k8ordo/form/docs/GUIDE.mdに入っています。AGENTS.mdなどからこのパスを参照させてください。

スキーマを読むformFieldsとparseFormはサーバーで動き、useFormはClient Componentで動きます。

情報

メモ

スキーマはzod/miniで書いても同じように動きます。クライアントのコードもスキーマのモジュールをimportするなら、バンドルの小さいzod/miniを選んでください。

スキーマの定義

src/lib/schema.ts
import * as z from 'zod';

export const talkSchema = z.object({
  title: z.string().min(1, 'Enter a title').max(120),
  eventUrl: z.url('Enter the event URL'),
  minutes: z.coerce.number().int().min(5).max(60),
});

フォームの入力欄と、それぞれの制約をzodのスキーマに書きます。minやurlに渡した文言は、そのままエラーの表示に使われます。

フォームは数値の入力欄の値も文字列として送ります。数値の入力欄はz.coerce.number()で定義し、文字列を数値に変換してから検証します。

入力欄の属性

src/routes/talks/new/page.tsx
import { formFields } from '@k8ordo/form/server';

import { TalkForm } from '../../../components/talk-form';
import { createTalk } from '../../../lib/actions';
import { talkSchema } from '../../../lib/schema';

const talkFields = formFields(talkSchema);
モジュールスコープで1回だけ作る

export default function NewTalkPage() {
  return <TalkForm action={createTalk} fields={talkFields} />;
}

Server ComponentでformFieldsにスキーマを渡します。入力欄に付けるrequiredやmaxlengthなどの属性と、エラーの文言が作られます。

戻り値はJSONなので、propsとしてClient Componentに渡せます。zodはブラウザのバンドルに入りません。

送信の検証

src/lib/actions.ts
'use server';

import { parseForm } from '@k8ordo/form/server';
import type { FormState } from '@k8ordo/form/server';
import { href } from '@k8ordo/framework';
import { redirect } from '@k8ordo/framework/server';

import { talkSchema } from './schema';
import { saveTalk } from './talks.server';

export async function createTalk(
  _prev: FormState,
  formData: FormData,
) {
  const parsed = parseForm(talkSchema, formData);
  if (!parsed.success) return parsed.state;

  await saveTalk(parsed.data);
  redirect(href('/talks'));
}

送信はServer Actionで受け取り、parseFormに同じスキーマとformDataを渡します。

検証に通ると、parsed.dataに型の付いた値が入ります。通らないときはparsed.stateを返します。エラーと入力した値がフォームに戻り、最初にエラーになった入力欄にフォーカスが移ります。

保存のあとの移動は@k8ordo/framework/serverのredirect()で行います。詳しくはServer Actionを見てください。

フォームの描画

src/components/talk-form.tsx
'use client';

import { useForm } from '@k8ordo/form';
import type { FormFields, FormState } from '@k8ordo/form';
import { useActionState } from 'react';

type Props = {
  action: (prev: FormState, formData: FormData) => Promise<FormState>;
  fields: FormFields<'title' | 'eventUrl' | 'minutes', never>;
};

export function TalkForm({ action, fields }: Props) {
  const [state, formAction] = useActionState(action, {});
  const form = useForm(fields, state);
入力欄の属性と、Server Actionが返したstate
  const title = form.field('title');
  const eventUrl = form.field('eventUrl');
  const minutes = form.field('minutes');

  return (
    <form {...form.props} action={formAction}>
`<form>`にだけ展開する
      <label>
        Title <input {...title.input} />
      </label>
      {title.error !== undefined && <p>{title.error}</p>}
      <label>
        Event URL <input {...eventUrl.input} />
      </label>
      {eventUrl.error !== undefined && <p>{eventUrl.error}</p>}
      <label>
        Length (minutes) <input {...minutes.input} />
      </label>
      {minutes.error !== undefined && <p>{minutes.error}</p>}
      <button type="submit">Submit</button>
    </form>
  );
}

useActionStateにServer Actionを渡します。返ってくるstateと、propsのfieldsをuseFormに渡します。

form.propsは<form>に、各欄のinputは対応する入力欄に展開します。エラーはerrorに入るので、入力欄のすぐ近くに表示します。

入力した値はReactのstateで管理しないので、キーを押すたびに再描画されることはありません。入力欄を1つずつ登録する手順もありません。

Playground

申し込みのデモ

ここまでで作ったフォームです。送信先が無いので、送信できる値になった時点で止まります。

試してみる

  1. 何も入力せずに「申し込む」を押します。最初の欄にフォーカスが移り、エラーが表示されます。
  2. 「イベントのURL」にexampleと入力して欄から離れます。「イベントのURLを入力してください」と表示されます。
  3. 「長さ(分)」に90と入力して欄から離れます。「60分以下にしてください」と表示されます。
k8ordo

Baselineに入った機能を、制限なく使うReactのライブラリ群。