[React Hook Form] Next.js 프로젝트에 React Hook Form 적용기

 

1. React Hook Form이란?

react-hook-form은 간단하고 효율적인 방식으로 폼 유효성 검사와 상태 관리를 처리할 수 있게 도와주는 React 기반의 폼 관리 라이브러리입니다.

1.1 프로젝트에서 React Hook Form을 도입한 이유

react-hook-form을 프로젝트에 도입한 가장 큰 이유는 '성능'과 '코드의 간결함' 때문입니다. React에서 폼을 처리하는 방식은 대부분 useState로 각 필드의 상태를 관리하는데, 이는 복잡한 폼일수록 코드가 길어지고 상태 변화마다 리렌더링이 발생하여 성능 저하로 이어질 수 있습니다. 이전 프로젝트에서 useState 기반으로 모든 필드 값을 상태로 관리하고, 각 필드가 변경될 때마다 폼 전체가 리렌더링되는 비효율적인 구조를 가지고 있어 이번 프로젝트에서 이를 개선하기 위해 react-hook-form을 도입했습니다.

 

react-hook-form은 비제어 컴포넌트와 Ref 기반으로 동작하여 상태 변화를 DOM에서 직접 관리하기 때문에, 상태 관리와 리렌더링 부담을 줄이는 동시에 성능을 최적화할 수 있습니다. 또한, 유효성 검사와 폼 상태 관리를 일관된 방식으로 처리할 수 있습니다. register와 validation을 통해 필드의 유효성 검사를 쉽게 정의할 수 있으며, 제출 시 유효성 검사를 통과하지 못한 필드에 대해 자동으로 에러 메시지를 처리할 수 있습니다.

 

기존 방식:

• useState로 각 필드마다 상태 관리 → 불필요한 리렌더링
• 유효성 검사를 위한 별도의 로직, 그에 따른 상태 관리의 복잡함

React Hook Form 방식:

• Ref로 상태 관리 → 리렌더링 최소화, 성능 최적화
• 기본적인 유효성 검사 추가 용이, 커스텀 유효성 검사 유연하게 처리

---

2. 프로젝트에 적용하기

2.1 프로젝트 구조에 맞춘 설정

프로젝트에서 폼을 구조화할 때, 먼저 FormProvider를 통해 react-hook-form의 폼 상태를 전역에서 관리하도록 설정했습니다. react-hook-form은 FormProvider와 useForm 훅을 이용해 폼 전체의 상태를 캡슐화합니다. 폼의 모든 상태는 methods 객체로 제공되며, 이를 통해 각 필드의 상태와 유효성 검사를 관리할 수 있습니다.

const methods = useForm<ISignUpRequest>({ 
  mode: 'onBlur', defaultValues: { 
    email: '', 
    password: '', 
    accountname: '', 
    username: '', 
    image: '', 
    intro: '', 
  }, 
});

FormProvider란?

FormProvider는 폼 상태를 전역적으로 관리하기 위해 사용하는 컴포넌트입니다. 즉, 폼 필드들이 여러 하위 컴포넌트로 나뉘어 있더라도, 각 컴포넌트에서 동일한 폼 상태를 공유하고 관리할 수 있도록 도와줍니다. 일반적으로 폼이 하나의 컴포넌트에서만 관리된다면 필요하지 않지만, 폼 필드가 여러 컴포넌트에 나뉘어져 있을 때는 FormProvider를 사용하여 폼 상태를 공유할 수 있습니다.

import { FormProvider, useForm } from 'react-hook-form';

export default function Signup() {
  const methods = useForm<ISignUpRequest>();
  
  return (
    <FormProvider {...methods}> {/* FormProvider로 감싸서 상태를 공유 */}
      <form>
        <AuthForm />  {/* AuthForm에서 useFormContext로 폼 상태를 접근 */}
        <ProfileForm /> {/* ProfileForm에서도 동일한 폼 상태 접근 */}
      </form>
    </FormProvider>
  );
}

useFormContext란?

useFormContext는 FormProvider로 감싸진 컴포넌트에서 폼 상태를 접근하기 위해 사용하는 훅입니다. 이 훅을 사용하면 컴포넌트 간에 동일한 폼 상태를 쉽게 공유할 수 있습니다. 아래와 같이 이메일, 비밀번호 입력 필드와 프로필 입력 필드가 서로 다른 컴포넌트에 있더라도, useFormContext를 사용하여 같은 폼 상태에 접근하고 처리할 수 있습니다.

import { useFormContext } from 'react-hook-form';

export default function AuthForm() {
  const { register, formState: { errors } } = useFormContext(); // 폼 상태 접근
  
  return (
    <div>
      <input {...register('email')} placeholder="이메일" />
      {errors.email && <span>{errors.email.message}</span>}
      <input {...register('password')} placeholder="비밀번호" />
      {errors.password && <span>{errors.password.message}</span>}
    </div>
  );
}

import { useFormContext } from 'react-hook-form';

export default function ProfileForm() {
  const { register, formState: { errors } } = useFormContext(); // 폼 상태 접근
  
  return (
    <div>
      <input {...register('username')} placeholder="사용자 이름" />
      {errors.username && <span>{errors.username.message}</span>}
    </div>
  );
}

2.2 기본 폼 컴포넌트 구현과 리팩토링

초기에 작성한 폼 컴포넌트는 AuthForm과 ProfileForm으로 나뉘어 각 필드를 개별적으로 처리하는 방식이었습니다. 동일한 레이아웃을 공유하지만 ProfileForm에서는 userimage를 받아야 했기 때문에 각각의 Form으로 나누어 구현하였습니다.

초기 AuthForm 컴포넌트:

'use client';

import { useFormContext } from 'react-hook-form';
import { UnderlineInput } from '@/components/common/input/UnderlineInput';

interface AuthFormProps {
  type: 'login' | 'signup';
}

const authFields = {
  signup: {
    email: {
      label: '이메일',
      placeholder: '이메일을 설정해주세요.',
    },
    password: {
      label: '비밀번호',
      placeholder: '비밀번호를 설정해주세요.',
    },
  },
  login: {
    email: {
      label: '이메일',
      placeholder: '이메일을 입력하세요.',
    },
    password: {
      label: '비밀번호',
      placeholder: '비밀번호를 입력하세요.',
    },
  },
};

export default function AuthForm({ type }: AuthFormProps) {
  const {
    register,
    formState: { errors },
  } = useFormContext();

  const fields = authFields[type];

  return (
    <fieldset className="flex-center gap-4">
      {Object.entries(fields).map(([name, field]) => (
        <UnderlineInput
          key={name}
          {...register(name)}
          isClearable
          variant="underlined"
          type={name}
          label={field.label}
          placeholder={field.placeholder}
          isInvalid={!!errors[name]}
          errorMessage={errors[name]?.message?.toString()}
        />
      ))}
    </fieldset>
  );
}

동일한 레이아웃으로 중복 코드가 많았기 때문에, AuthForm과 ProfileForm을 하나의 FormTemplate 컴포넌트로 리팩토링하여 폼 필드를 동적으로 관리하도록 변경했습니다.

리팩토링 후 FormTemplate 컴포넌트:

'use client';

import { useFormContext } from 'react-hook-form';

import { UnderlineInput } from '@/components/common/input/UnderlineInput';
import { IFields } from '@/config/authFieldConfig';

interface FormTemplateProps {
  fields: IFields;
  children?: React.ReactNode; // 추가적인 컴포넌트(프로필 사진) 받을 수 있음
}

export default function FormTemplate({ fields, children }: FormTemplateProps) {
  const {
    register,
    formState: { errors},
  } = useFormContext();

  return (
    <fieldset className="flex-center gap-4">
      {children}
      {Object.entries(fields).map(([name, field]) => {  
        <UnderlineInput
            key={name}
            {...register(name, field.validation)}
            isClearable
            variant="underlined"
            type={
              name === 'email'
                ? 'email'
                : name === 'password'
                  ? 'password'
                  : 'text'
            }
            label={field.label}
            placeholder={field.placeholder}
            isInvalid={!!hasError}
            errorMessage={errors[name]?.message?.toString()}
          />
      })}
    </fieldset>
  );
}

부모 컴포넌트로부터 fields(예: SIGN_UP_FIELDS, PROFILE_FIELDS, LOGIN_FIELDS)와 children을 props로 받아 폼이 구성되도록 수정했습니다. 이 덕분에 폼 필드에 대해 더 간결하게 코드를 작성할 수 있었으며, 유지보수성이 향상되었습니다.

---

3. 트러블슈팅: 중복된 유효성 검사

회원가입 시 스텝 기반 폼 구조를 사용하면서, 다음 스텝으로 넘어갈 때마다 유효성 검사가 트리거되어 렌더링되는 문제가 있었습니다.

에러가 발생하는 이유는 react-hook-form의 기본 동작 방식 때문이었습니다. 폼 필드가 렌더링되는 순간, 유효성 검사가 즉시 실행되어, 스텝이 변경될 때마다 입력값이 없음에도 불구하고 바로 유효성 검사가 발생하는 것이 문제였습니다.

해결 방법

1. clearErrors() 사용(해결X) : 스텝 변경 시 이전의 유효성 검사 오류를 초기화하기 위해 clearErrors()를 사용했지만, 여전히 프로필 필드가 렌더링될 때 유효성 검사가 발생했습니다.
2. touchedFields 활용(해결O) : FormTemplate 컴포넌트에 touchedFields를 추가하여, 필드가 터치된 경우에만 유효성 검사 오류를 표시하도록 수정했습니다. touchedFields는 사용자가 필드를 한 번이라도 클릭하거나 편집을 시도했는지를 추적하며, 이를 통해 스텝 변경 시 자동으로 유효성 검사 오류가 발생하지 않도록 제어할 수 있었습니다.

---

4. 회고

4.1 React Hook Form 사용의 장단점

장점:

• 폼 성능 최적화: 이전 프로젝트에서 useState로 모든 필드의 상태를 관리했을 때, 복잡한 폼에서 빈번한 리렌더링이 발생해 성능 저하를 체감한 적이 있습니다. 반면, react-hook-form은 Ref 기반으로 상태를 관리해 불필요한 리렌더링을 최소화하면서도 빠른 반응성을 유지할 수 있었습니다.
• API의 직관성과 유지보수성: 처음 도입할 때는 상대적으로 생소했지만, register, handleSubmit, setError 같은 함수가 매우 직관적이라 금방 익숙해질 수 있었습니다. 특히, 유효성 검사 로직을 한 곳에서 통합 관리하면서, 코드가 깔끔해지고 유지보수성이 크게 향상되었습니다. 나중에 요구사항이 변경되더라도 폼의 구조와 유효성 검사를 손쉽게 조정할 수 있어, 반복 작업이나 수정할 부분이 적었습니다.
• 유연한 유효성 검사: 기본적인 유효성 검사는 register 옵션을 통해 쉽게 처리할 수 있었고, 복잡한 검증 로직은 validate 속성을 활용해 유연하게 확장할 수 있었습니다. 

단점:

• 초기 적응의 어려움: 처음에는 FormProvider와 useFormContext를 어떻게 활용해야 할지, 각 필드의 상태를 어떻게 최적화할지 고민이 많이 되었습니다. 특히 스텝 기반 폼에서 각 스텝에 따라 필드를 관리하고 유효성 검사를 처리하는 부분에서 복잡함을 느꼈습니다. 프로젝트 초반에는 생각보다 많은 시간이 걸렸지만, 익숙해지고 나니 이 방식이 더 직관적이면서도 강력하다는 것을 깨달았습니다.

4.2 향후 개선 방향

• 유효성 검사 최적화: 서버와의 유효성 검사 로직을 더 효율적으로 관리하기 위해 커스텀 훅을 개선할 예정입니다. 특히 이메일이나 계정 이름 같은 필드에 대한 서버 유효성 검사를 개선할 계획입니다.
• 테스트 코드 작성: 각 폼 필드에 대한 유효성 검사 및 폼 제출 테스트를 진행할 예정입니다. 이를 위해 Jest를 사용해 유효성 검증 테스트를 작성하여 프로젝트의 안정성을 더욱 강화할 예정입니다.