sicilian을 소개합니다

프론트엔드 분야에서 form 상태 관리 도구로 널리 쓰이는 react-hook-form은 ref를 기반으로 동작합니다. 이 때문에 컴포넌트를 forwardRef로 감싸거나, 라이브러리에서 제공하는 useFormContext를 사용해야 합니다. React.js를 사용하는 개발자로서 이러한 제약 사항이 여러모로 불편하게 느껴졌습니다.

sicilian은 이러한 불편함을 해결하기 위해 전역 상태를 기반으로 개발되었습니다. 이는 sicilian이 각각의 input을 state로 관리하며, 제어 컴포넌트 방식으로 form을 작성하도록 도움을 줄 수 있다는 뜻이기도 합니다. Sicilian은 React의 Context API를 내부적으로 활용하여 폼 상태를 전역적으로 관리하며, 이를 통해 별도의 전역 상태 관리 라이브러리(예: Redux, Zustand) 없이도 원하는 컴포넌트 어디에서나 폼 상태에 접근하고 조작할 수 있습니다.

sicilian@4.0.0에서 새로 추가된 것#

기존 register 대신 훅 스타일의 useRegister로 변경되고, (name, options) 시그니처로 정리되었습니다.
useFields가 value/error와 함께 touched, dirty, isValid 메타를 반환합니다.
값/에러 조회는 useFields로 통합되었고 getValues/getErrors는 제공되지 않습니다.
SicilianProvider 컨텍스트는 useRegister와 옵션 useFields를 사용합니다.
resolver import 경로가 @ilokesto/sicilian/resolver/zod, /yup, /superstruct로 분리되었습니다.

설치 방법#

sicilian은 아래의 다양한 방법으로 설치할 수 있습니다.

install.sh

npm install @ilokesto/sicilian
pnpm add @ilokesto/sicilian
yarn add @ilokesto/sicilian
bun add @ilokesto/sicilian

빠른 시작#

아래 예시는 sicilian의 기본적인 사용법을 보여줍니다. 이 예시에서는 간단한 로그인 폼을 구현하고 있으며, 이메일과 비밀번호 필드에 대한 유효성 검사를 포함하고 있습니다. sicilian의 폼 컨트롤러를 사용하여 폼 상태를 관리하고, 각 입력 필드에 대한 오류 메시지를 표시하는 방법을 확인할 수 있습니다.


import { useForm } from '@ilokesto/sicilian';

export default function MySimpleForm() {
  const { useRegister, handleSubmit, useFields } = useForm({
    initValue: {
      name: '',
      email: ''
    },
    validator: {
      name: {
        required: { required: true, message: 'name is required' }
      },
      email: {
        required: { required: true, message: 'email is required' },
        RegExp: {
          RegExp: /^[a-zA-Z0-9+-_.]+@[a-zA-Z0-9-]+.[a-zA-Z0-9-.]+$/,
          message: 'email format is invalid'
        }
      }
    }
  });

  const onSubmit = (data) => {
    console.log('data:', data);
  };

  const nameField = useFields('name');
  const emailField = useFields('email');

  return (
    <form onSubmit={handleSubmit(onSubmit)}>
      <div>
        <label htmlFor="name">name:</label>
        <input id="name" {...useRegister('name', { type: 'text' })} />
        {nameField.error}
      </div>

      <div>
        <label htmlFor="email">email:</label>
        <input id="email" {...useRegister('email', { type: 'email' })} />
        {emailField.error}
      </div>

      <button type="submit">login</button>
    </form>
  );
}