개인적으로 프론트엔드에서 개발하다보면 생각보다 많이 다루게 되고, 의외로 성가신 부분이 바로 Form 제출과 관련된 부분이라고 생각해요. Field에 대한 제약도 걸어줘야 하며, Client Validation을 통해서 원하는 값이 들어갔는지 확인을 해주어야 하며, 폼 제출 후 Server Validation을 통과했는지에 대한 여부를 검사해야 하기도 하고, 해당 폼이 다른 곳에서 쓰이는 확장성도 생각해보아야 해요.

물론 ,, 그냥 냅다 폼 제출 갈기고 서버에서 받아오는 Validation만 확인해도 되겠지만, 조금 더 유저들에게 친절한 여행을 제공해주기 위한 노력이라고 생각하며 이번 포스팅을 시작해볼게요^~^

---

Basic Form Structure

사실 form 태그를 사용하지 않고도 폼 제출에 대한 기능을 구현할 수 있어요. 버튼을 클릭하면 JS를 통해서 해당하는 필드들의 값을 체크하고, API 호출을 통해 서버에서 결과값을 받아올 수 있어요. (비동기 제출 방법으로)

폼을 제출하는 기능은 예전부터 많이 써왔던 기능이라 그렇게 하나하나 구현하지 않고도 <form> 이라는 객체가 제공해주는 폼 제출에 대한 흐름을 십분 활용하면 더욱 괜찮은 폼 제출 흐름을 구현할 수 있어요.

그리고, RHF과 Zod는 이러한 기본 폼 구조를 잘 활용할 수 있게 도와주는 역할인 거죠. 그렇기에 먼저 기본 폼 구조에 대해서 알아보고, RHF과 Zod를 살펴보는 것이 좋아보여요.

다만,, 여기 포스트에서 담기엔 해당 내용이 생각보다 살펴볼 게 많아서 언젠가의 다른 포스트로 다뤄볼까 해요. 여기에서는 RHF와 Zod에 집중하는 걸로!

만약 기본적인, 그리고 Standard한 폼 제출에 대한 전반을 알고 싶으시다면 MDN에서 제공하는 Web form building blocks 시리즈를 읽어보시길 추천드릴게요.

---

RHF(React Hook Form)

React에서 Form 제출에 관한 기능을 Controlled Component로 만든다면 아래와 같은 형식이 나오게 될 거에요.

로그인 폼 예시

function LoginForm() {
  const [email, setEmail] = useState('');
  const [password, setPassword] = useState('');

  const handleSubmit = (event) => {
    event.preventDefault();
    console.log('Submitted', { email, password });
  };

  return (
    <form onSubmit={handleSubmit}>
      <div>
        <label htmlFor="email">이메일:</label>
        <input
          type="email"
          id="email"
          value={email}
          onChange={(e) => setEmail(e.target.value)}
        />
      </div>
      <div>
        <label htmlFor="password">비밀번호:</label>
        <input
          type="password"
          id="password"
          value={password}
          onChange={(e) => setPassword(e.target.value)}
        />
      </div>
      <button type="submit">로그인</button>
    </form>
  );
}

지금은 이메일과 비밀번호만을 처리하는 경우라 상태가 많이 필요하지 않고 이에 따른 Validation이 복잡하지 않을 테지만, 만약 회원가입과 같이 여러 필드를 다루고 처리해야 하는 경우에는 무수한 많은 상태들이 생기게 될 테고, 관리하기가 매우 까다로워 질거에요.

이럴 때 RHF를 사용하게 되면 폼 제출에 대한 내용을 쉽게 다룰 수 있게 됩니다. RHF에선 입력한 폼 필드에 대해서 Controlled Component로 접근하는 것이 아니라 Uncontrolled하게 접근하게 됩니다.

Controlled/Uncontrolled Component

Controlled Component: React 상태로 관리하고 있는 컴포넌트를 말해요.
Uncontrolled Component: React 상태로 관리하지 않는 컴포넌트를 말해요.

React Hook Form에서 말하는 컨셉

Performance is one of the primary reasons why this library was created. React Hook Form relies on an uncontrolled form, which is the reason why the register function captures ref and the controlled component has its re-rendering scope with Controller or useController.

성능은 이 라이브러리가 만들어진 주요 이유 중 하나입니다. React Hook Form은 uncontrolled form에 의존하는데, 이는 register 함수가 ref를 캡처하는 이유이며, Controller나 useController와 함께 사용되는 controlled component는 재렌더링 범위가 있기 때문입니다.

출처: https://react-hook-form.com/faqs

상태로 필드에 대한 입력을 관리하지 않으니 불필요한 Re-rendering이 줄어들기도 하고, 직접 필드에 제약을 걸어줌으로써 보다 직관적인 동작을 예상할 수 있어요. 즉, 성능이 개선되고 예상하기도 좋은 코드가 되는 거죠.

RHF의 동작

RHF의 모든 동작은 useForm으로부터 시작합니다. useForm Hook에서 반환하는 것들로 form 동작을 핸들링하고, Field에 관한 제약을 걸게 됩니다. 아래의 코드를 보면 이해가 더 쉬울 것 같아요.

RHF Example

import { useForm, SubmitHandler } from "react-hook-form"

type Inputs = {
  example: string
  exampleRequired: string
}

export default function App() {
  const {
    register,
    handleSubmit,
    watch,
    formState: { errors },
  } = useForm<Inputs\>()
  const onSubmit: SubmitHandler<Inputs\> = (data) => console.log(data)

  console.log(watch("example")) // watch input value by passing the name of it

  return (
    /* "handleSubmit" will validate your inputs before invoking "onSubmit" \*/
    <form onSubmit={handleSubmit(onSubmit)}>
      {/* register your input into the hook by invoking the "register" function */}
      <input defaultValue="test" {...register("example")} />

      {/* include validation with required or other standard HTML validation rules */}
      <input {...register("exampleRequired", { required: true })} />
      {/* errors will return when field validation fails  */}
      {errors.exampleRequired && <span>This field is required</span>}

      <input type="submit" />
    </form>
  )
}

현재 useForm에서 나오는 register, handleSubmit, watch, formState를 사용하면 기본적인 폼 제출을 구현할 수 있어요. 다른 것들도 많지만, 일단 기본!

register

Usage in example

<input {...register("exampleRequired", { required: true })} />

먼저 눈에 띄는 건 register의 존재입니다. register는 함수인데, 해당 함수에 인자를 넣어서 input element prop으로 넘겨주고 있어요. 그렇다면 해당 함수는 input element과 관련이 있는 녀석이겠죠? RHF 공식 문서에서 해당 함수의 원형과 설명을 보면 다음과 같아요.

register()

This method allows you to register an input or select element and apply validation rules to React Hook Form. Validation rules are all based on the HTML standard and also allow for custom validation methods.

register: (name: string, RegisterOptions?) => ({ onChange, onBlur, name, ref })

보다 자세한 설명은 여기

중요한 것 같은 문구는 강조 표시를 해놨어요. 해당 부분만 본다면 register는 다음과 같은 역할을 한다고 볼 수 있겠네요: HTML 표준에 따른 유효성 검사!

또, 반환 값으로 나온 값들을 보면 onChange, onBlur, name, ref를 반환하고 있어요. 이는 결국 위의 예제에서 본 코드가 다음과 같다는 걸 알 수 있어요.

register()의 동작

const { onChange, onBlur, name, ref } = register('firstName'); 
// include type check against field path with the name you have supplied.

<input 
  onChange={onChange} // assign onChange event 
  onBlur={onBlur} // assign onBlur event
  name={name} // assign name prop
  ref={ref} // assign ref prop
/>
// same as above
<input {...register('firstName')} />

코드를 보면 register로 input의 name을 지정해주고, onChange와 onBlue의 이벤트를 구독받아서 대신 처리해줌을 알 수 있어요.

위의 설명들을 하나로 정리하여 register를 설명한다면, (1) Form Field에 대한 속성 부여 및 (2) 유효성 검사에 필요한 이벤트를 구독하는 역할 정도로 설명할 수 있을 것 같아요.

handleSubmit

Usage in example

const onSubmit: SubmitHandler<Inputs\> = (data) => console.log(data)
<form onSubmit={handleSubmit(onSubmit)} />

그 다음은 handleSubmit입니다. 이 함수는 현재 form element의 onSubmit에 넘겨주고 있고, 인자에 따로 만든 Handler를 넣어주고 있어요. 그렇다면 이 녀석은 (당연하게도) 제출과 관련된 녀석이겠네요!

handleSubmit()

This function will receive the form data if form validation is successful.

handleSubmit: ((data: Object, e?: Event) => Promise<void\>, (errors: Object, e?: Event) => void) => Promise<void\>

중요한 말이 나왔네요. handleSubmit은 폼의 유효성이 성공적일 때만 form data를 받는다고 하네요. 다시 말하면, form validation이 통과하지 않으면 해당 함수가 호출되지 않는다는 말과 같아요.

handleSubmit의 인자

Name	Type	Description
SubmitHandler	(data: Object, e?: Event) => Promise<void>	A successful callback.
SubmitErrorHandler	(errors: Object, e?: Event) => Promise<void>	An error callback.

즉, Form Validation이 성공하면 첫 번째 인자인 SubmitHandler이 호출되고, 실패하게 되면 두 번째 인자인 SubmitErrorHandler가 호출이 됩니다. 실제로 handleSubmit을 호출할 땐 두 번째 인자는 Optional Parameter이기 때문에 생략이 가능해요.

handleSubmit의 타입

export type UseFormHandleSubmit
  <TFieldValues extends FieldValues, TTransformedValues extends FieldValues | undefined = undefined>
  = (onValid: TTransformedValues extends undefined 
    ? SubmitHandler<TFieldValues\>
    : TTransformedValues extends FieldValues
      ? SubmitHandler<TTransformedValues\>
      : never,
  onInvalid?: SubmitErrorHandler<TFieldValues\>) => (e?: React.BaseSyntheticEvent)
  => Promise<void\>;

이때 재밌는 포인트는 성공 시에 호출되는 onValid(SubmitHandler)는 인자로 Object를 받는다는 점인데요, 이 Object는 FormData 객체가 아니라 말 그대로 'Object'가 반환이 됩니다(!) 이 Object는 등록된 Field의 이름과 그에 대한 값이 들어오게 돼요.

현재 공시락 서비스에서 사용되고 있는 폼 제출에서 로그를 찍어본 결과 인데요, data에 들어온 값이 바로 onValid로 들어온 Object 그대로의 값입니다.

원래대로라면 FormData 형식으로 들어오기 때문에 Object.fromEntries()와 같은 함수를 이용해 Object로 반환하는 과정이 필요했는데, 그런 번거로운 과정 없이 Object를 얻을 수 있는 게 장점인 것 같아요.

formState

그렇다면 유효성 검사를 통과하지 못하면 어떻게 될까요? 그럴 땐 SubmitErrorHandler가 호출이 되어 Error에 대한 값이 담겨오게 되는데요, 그렇지만 이 방법은 Client Validation을 적절하게 핸들링할 수 없어요. 에러에 대한 내용을 함수 바깥에서 접근할 수 있어야 오류 메시지를 표현할 수 있을 테니까요.

그렇기 때문에 에러 메시지를 보여주기 위해 onInvalid()를 쓰진 않고, 그 용도라면 formState를 받아서 쓰는 구조가 많아요.

Usage in example

{ formState: { errors } } = useForm<Inputs\>()
{errors.exampleRequired && <span>This field is required</span>}

현재 예시에서는 formState에서 errors를 빼오고, 해당 errors에 exampleRequired가 존재한다면 에러 메시지를 표출하고 있어요. 그 말은? errors의 exampleRequired가 fasly할 수도 있다는 이야기가 되겠네요.

이에 대해서 콘솔로 직접 오류를 찍어보면 다음과 같은 결과를 얻을 수 있어요.

errors가 비어있는 객체일 때도 있고, 값을 가진 형태일 때도 있네요. 즉, errors는 유효성 검사를 통과하지 못한 필드에 대해 message를 담아서 넘겨주고 있어요.

그렇기 때문에 errors에 있는 속성 값은 '에러가 있을 때만' 존재하기 때문에 손쉽게 error message를 판단할 수 있게 되는 거죠.

---

Zod

RHF는 위에서 설명한 것 이 외에도 폼 제출과 관련되어 편리한 기능을 많이 지원하고 있어요. 다만, 개인적으로 조금 아쉬운 점을 뽑자면 Field에 대한 유효성 검사들이 흩어져 있다는 점이에요.

RHF는 Field 각각에 대해서 등록을 진행하기 때문에 해당 필드의 유효성을 알기 위해서는 직접 필드까지 찾아가야 해요. 물론, 필드가 적은 폼이라면 해당 방식이 큰 문제는 없겠지만 역시나 문제는 필드가 많아질 때 발생하는 것 같아요.

그렇다면, 한 필드마다 제약을 거는 게 아니고 만약 폼에서 제출할 필드들에 대해서 미리 규격을 만들어 놓고 제어를 하면 조금 더 알아보기 쉽고 편리하지 않을까요?

Zod는 '폼 스키마(Form Schema)' 기반으로 유효성 검사를 진행하는 패키지에요. 이 Zod를 사용함으로써 얻을 수 있는 장점은 간편한 유효성 검사이기도 하지만, 런타임 환경에서도 타입을 확정해준다는 점이에요. 타입스크립트는 빌드시에 타입을 잡아내기에 런타임에서 실제로 해당 값이 그렇게 오리라는 보장을 해주진 못해요. 하지만 이 Zod를 이용해 타입을 확실하게 해주어 타입과 관련된 오류를 잡아줄 수 있어요.

이 Zod과 RHF를 같이 쓸 수 있는데 그것은 더 아래 Section에서 다뤄보도록 하고, 먼저 Zod의 사용법을 가볍게 알아볼게요.

*참고) Zod가 제공하는 기능이 아주아주 많아서, 이 포스트에서는 필요한 부분만 다뤄볼게요.

Form Schema 정의

폼 스키마라고 해서 좀 복잡할 것 같지만, 그런 마음이 무색하게 정말 타입에 대한 내용 뿐이에요. 기본적인 스킴을 정하는 방법은 아래와 같아요.

String Schema

import { z } from "zod";

// creating a schema for strings
const mySchema = z.string();

// parsing
mySchema.parse("tuna"); // => "tuna"
mySchema.parse(12); // => throws ZodError

// "safe" parsing (doesn't throw error if validation fails)
mySchema.safeParse("tuna"); // => { success: true; data: "tuna" }
mySchema.safeParse(12); // => { success: false; error: ZodError }

이러면 mySchema는 string 타입에 대한 스키마가 되는 것 뿐이에요! 끝! 아주 간단하죠?

parse와 safeParse

해당 스키마로 값의 유효성을 검사하는 방법에는 두 가지가 있어요. parse와 safeParse입니다. 둘 다 성공하면 값을 반환하지만 실패했을 경우 처리가 달라요.

parse와 safeParse의 차이점

parse(): 실패하면 ZodError를 throw합니다.
safeParse(): 실패해도 throw를 하지 않아요.

왜 parse일까?

호출하는 메서드의 이름이 parse인 이유는, 말 그대로 결과값을 파싱하기 때문이에요. 사실 Zod에서 유효성을 검사하면 다음과 같은 결과를 기반으로 결과를 반환한답니다.

ZodIssue

[
  {
    "validation": "email",
    "code": "invalid_string",
    "message": "Invalid email",
    "path": []
  },
  {
    "code": "invalid_string",
    "validation": { "endsWith": "example.com" },
    "message": "Invalid input: must end with \"example.com\"",
    "path": []
  }
]

특정 형식에 대해서 정보를 얻는 형태이므로, Parse인 것!

object Schema

해당 방식을 기본으로, object라는 schema 역시 지정해줄 수 있고, 각 필드마다 새로운 schema를 지정해줄 수 있어요.

object Schema

import { z } from "zod";

const User = z.object({
  username: z.string(),
});

User.parse({ username: "Ludwig" });

// extract the inferred type
type User = z.infer<typeof User\>;
// { username: string }

현재 User라는 Schema는 object를 받고 있고, username이라는 key는 string이라는 스킴을 설정한 상태입니다. 이렇게 각 필드에 대해서 스킴을 걸어줄 수 있으니, 여러 폼 필드에 대해서 각각 설정해줄 수 있겠죠?

Validation Chaining

Zod의 매력은 여기에서 더 나아가서, 하나의 필드에 하나의 제약만 걸 수 있는 것이 아니라 여러 제약을 걸 수도 있으며 기본적으로 제공하는 제약들이 많다는 점이에요.

string 관련 유효성 검사

// validations
z.string().max(5);
z.string().min(5);
z.string().length(5);
z.string().email();
z.string().url();
z.string().emoji();
z.string().uuid();
z.string().nanoid();
z.string().cuid();
z.string().cuid2();
z.string().ulid();
z.string().regex(regex);
z.string().includes(string);
z.string().startsWith(string);
z.string().endsWith(string);
z.string().datetime(); // ISO 8601; by default only `Z` timezone allowed
z.string().ip(); // defaults to allow both IPv4 and IPv6

// transforms
z.string().trim(); // trim whitespace
z.string().toLowerCase(); // toLowerCase
z.string().toUpperCase(); // toUpperCase

// added in Zod 3.23
z.string().date(); // ISO date format (YYYY-MM-DD)
z.string().time(); // ISO time format (HH:mm:ss[.SSSSSS])
z.string().duration(); // ISO 8601 duration
z.string().base64();

문자열의 최소 길이, 최대 길이부터 시작해서 특정 형식인지도 판단할 수 있고, 패턴을 통한 유효성 검사도 할 수 있어요. 물론 이것 전부 중복해서 쓸 수 있다는 점! 완전 짱이다!

예를 들면 다음과 같이 사용자 이름에 대한 Validation을 걸 수 있어요.

Username에 대한 여러 유효성 검사

z.object({
  username: z.string().min(2).max(10)
})

Custom Validation

Zod에서 제공하는 유효성 검사 목록들 뿐만 아니라, 본인이 직접 유효성 검사를 만들어 적용할 수도 있어요. 예를 들어서, 회원가입 상황에서 비밀번호 확인과 같은 상황이요!

비밀번호 확인 유효성 검사

const passwordForm = z
  .object({
    password: z.string(),
    confirm: z.string(),
  })
  .refine((data) => data.password === data.confirm, {
    message: "Passwords don't match",
    path: ["confirm"], // path of error
  });

passwordForm.parse({ password: "asdf", confirm: "qwer" });

refine이라는 메서드를 통해서 특정한 제약을 지정해줄 수 있는데요, 이 메서드에서 첫 번째 인자로 해당하는 스킴 데이터가 들어오게 되고, 해당 데이터를 이용해 제약을 걸어줄 수 있어요. 위의 예시에선 password와 confirm을 비교해서 나타내고 있고, 해당하는 메시지 역시 포함해서 지정해주고 있어요.

알아두면 좋은 점은 꼭 'boolean'형을 반환하지 않아도 된다는 점입니다. Zod의 이전 버전에선 꼬옥 boolean을 반환해야 했지만, 업데이트된 버전에서는 truthy한 값이라면, 그러니까 falsy한 값이 아니라면 유효성 검사를 통과한 것으로 간주하게 돼요.

Refine의 Validation Function

The first is the validation function. This function takes one input (of type T — the inferred type of the schema) and returns any. Any truthy value will pass validation. (Prior to zod@1.6.2 the validation function had to return a boolean.)

첫 번째는 validation 함수입니다. 이 함수는 하나의 입력값(스키마의 추론된 타입 T)을 받아서 any를 리턴합니다. 어떤 truthy한 값이든 validation을 통과시킵니다.(zod@1.6.2 이전 버전에서는 validation 함수가 boolean을 리턴해야 했습니다.)
출처: https://zod.dev/?id=arguments

*참고) refine에서 정의한 유효성 검사는 throw를 던지지 않아요.

Customize Error Message

safeParse를 기준으로 해당 스킴에 대해서 유효성을 통과하지 못하면 Error Message를 반환하게 되는데요, 이 Error Message는 기본적으로 ZodError내의 default error map에 의해서 정의되어 있어요. 굳이 궁금하시다면 여기에서 확인할 수 있어요

해당 메시지를 그냥 쓸 수 있겠지만, 보통은 그러지 않고 서비스 정책 내에 정의된 메시지를 사용하게 될 거에요. 그런 메시지는 아래와 같이 아주 편하게 설정할 수 있답니다.

Error Message 지정

z.object({
  username: z
    .string({ message: "사용자 이름은 문자열이어야 해요." })
    .min(2, '사용자 이름은 최소 2글자여야 해요.')
    .max(10, '사용자 이름은 최대 10글자 이하여야 해요.'),
})

각 유효성 검사에 대한 메시지를 함께 지정해줄 수 있으니 좀 더 보기가 편해졌죠? 개인적으로 유효성 검사와 에러 메시지를 한 번에 정해줄 수 있어서 좋더라구요.

---

RHF + Zod Resolver

그렇다면~ RHF의 폼 객체 제어 기능과 Zod의 유효성 검사를 합치게 된다면 폼 제출을 더 편하게 다룰 수 있게 되지 않겠어요? 당연하게도 이런 기능을 제공하고 있다는 점!

Resolver를 통한 RHF과 Zod 통합

import { useForm } from 'react-hook-form';
import { zodResolver } from '@hookform/resolvers/zod';

const formSchema = z
  .object({
    username: z
      .string({ message: "사용자 이름은 문자열이어야 해요." })
      .min(2, '사용자 이름은 최소 2글자여야 해요.')
      .max(10, '사용자 이름은 최대 10글자 이하여야 해요.'),
    password: z.string(),
    confirm: z.string(),
  })
  .refine((data) => data.password === data.confirm, {
    message: "비밀번호가 일치하지 않아요.",
    path: ["confirm"],
  });

type FormSchemaType = z.infer<typeof formSchema\>;

const initialValues: FormSchemaType = {
  username: '',
  password: '',
  confirm: ''
};

const form = useForm<FormSchemaType\>({
  resolver: zodResolver(formSchema),
  defaultValues: { ...initialValues },
});

React Hook Form에서는 Resolver라는 기능을 제공함으로써 외부에서 Validation을 진행할 수 있게 했어요. 마찬가지로 Zod에서도 이에 대한 Resolver를 제공하고 있구요. 보다 자세한 정보는 여기!

생각보다 엄청 간단하죠?

Example

이대로 포스팅을 끝내긴 아쉬우니까, 이를 토대로 간단하게 이메일, 비밀번호, 비밀번호 확인, 유저 이름을 받는 폼을 만들어볼게요.

AI가 생성해준 회원가입 폼 코드에 내가 수정한 코드

const formSchema = z
  .object({
    email: z.string().email({ message: '이메일 형식으로 입력해주세요.' }),
    password: z
      .string()
      .min(2, { message: '비밀번호는 최소 2글자여야 합니다.' })
      .max(10, { message: '비밀번호를 최대 10글자 이하로 정해주세요.' }),
    username: z
      .string()
      .min(2, { message: '유저이름은 최소 2글자여야 합니다.' })
      .max(10, { message: '유저 이름을 최대 10글자 이하로 정해주세요.' }),
  })
  .refine((data) => data.password !== data.passwordConfirmation, {
    message: '입력한 비밀번호와 같지 않아요.',
    path: ['passwordConfirmation'],
  });

// 폼 입력 타입 정의
type FormData = z.infer<typeof formSchema\>;

export function SignUpForm() {
  const {
    register,
    handleSubmit,
    formState: { errors },
  } = useForm<FormData\>({
    resolver: zodResolver(formSchema),
  });

  const onSubmit: SubmitHandler<FormData\> = (data) => {
    console.log(data);
  };

  return (
    <form onSubmit={handleSubmit(onSubmit)}>
      <div>
        <label htmlFor="email">이메일</label>
        <input id="email" type="email" {...register('email')} />
        {errors.email && <p>{errors.email.message}</p>}
      </div>
      <div>
        <label htmlFor="password">비밀번호</label>
        <input id="password" type="password" {...register('password')} />
        {errors.password && <p>{errors.password.message}</p>}
      </div>
      <div>
        <label htmlFor="passwordConfirmation">비밀번호 확인</label>
        <input id="passwordConfirmation" type="password" {...register('passwordConfirmation')} />
        {errors.passwordConfirmation && <p>{errors.passwordConfirmation.message}</p>}
      </div>
      <div>
        <label htmlFor="username">유저이름</label>
        <input id="username" type="text" {...register('username')} />
        {errors.username && <p>{errors.username.message}</p>}
      </div>
      <button type="submit">회원가입</button>
    </form>
  );
}

아 편하다

---

RHF과 Zod의 기본 동작부터 알아보느라 포스트가 길어지긴 했는데, 결국엔 합치는 건 Resolver만 쓰면 되는 일이라(ㅋㅋ)

그래도 덕분에 좀 더 잘 쓸 수 있을 것 같다!