프레임워크 밖에서 폼을 관찰하는 법: 시리즈 가이드
작성일:2026.11.03|수정일:2026.11.03|조회수:9

폼 개발은 처음에는 값을 읽고 검증 결과를 보여 주는 일로 시작한다. 그런데 필드가 늘어나면 dirty, touched, modified 같은 상태가 붙고, 배열 필드와 제출 상태와 오류 경로까지 따라온다. React, Vue, Solid, Svelte가 같은 코어의 Form<TValues>를 사용하기 시작하면, Form을 들여다보는 도구도 어느 프레임워크 편에 서야 하는지 애매해진다.
@ilokesto/form의 Form Devtools는 이 지점에서 출발했다. React용 상태 패널과 Vue용 상태 패널을 따로 만드는 대신, Form이 제공하는 관찰 능력만 계약으로 떼어내고 그 계약을 읽는 UI를 Web Component로 만든다. 결과물은 <ilokesto-form-devtools> 하나지만, 이 하나를 만들기 위해 관찰 계약, 브라우저 생명주기, DOM 경계, 반응형 렌더링, 프레임워크 통합을 서로 다른 책임으로 나눠야 했다.
프레임워크 독립성은 아무 프레임워크도 쓰지 않는다는 뜻이 아니다. 핵심 구현이 어느 프레임워크의 상태와 생명주기를 소유할지 정하는 일에 가깝다.
이 시리즈는 완성된 Devtools의 기능을 순서대로 소개하지 않는다. 같은 구현을 여러 프레임워크에서 사용하려면 무엇을 공통 계약으로 남기고, 무엇을 브라우저에 맡기며, 무엇을 얇은 어댑터로 밀어내야 하는지 따라간다.
이 시리즈가 다루는 것
본편: 관찰 계약에서 프레임워크 통합까지
프레임워크가 달라도 같은 폼을 관찰할 수 있는 이유는 프레임워크별 반응성을 직접 통합하는 대신 getState(), getValues(), subscribe()만 남긴 읽기 전용 관찰 계약에서 시작한다. Devtools가 Form<TValues>의 모든 기능을 아는 순간 결합도 함께 커지기 때문에, 무엇을 할 수 있는지보다 무엇을 몰라도 되는지를 먼저 정한다.
브라우저에 Form Devtools를 등록하기는 그 계약을 받는 UI를 Custom Element로 옮긴다. 객체는 Attribute가 아니라 Property로 전달하고, DOM 연결·해제에 맞춰 외부 Form 구독을 시작하고 정리한다. 프레임워크의 컴포넌트 생명주기 대신 브라우저의 생명주기를 기준으로 삼는 구간이다.
애플리케이션 안에서 독립적으로 떠 있는 UI 만들기와 FormState를 화면으로 옮기다 Lit이 필요해지는 순간은 비슷해 보이지만 다른 문제를 다룬다. Shadow DOM은 호스트 애플리케이션과 Devtools 사이의 DOM·스타일·이벤트 경계를 만든다. Form 구독이 새 스냅숏을 내부 상태에 옮기면, Lit은 그 변경을 화면에 반영한다. Web Component, Shadow DOM, Lit을 한 덩어리로 부르지 않고 각각 무엇을 책임지는지 나누는 이유가 여기에 있다.
마지막 본편인 React에서 Web Component를 React 컴포넌트처럼 사용하기는 완성된 Custom Element를 React 19에서 직접 사용하는 방식과 @lit/react 래퍼를 비교한다. 래퍼가 Form 구독이나 화면을 다시 만들지 않고 Property, 이벤트, 타입과 ref만 React의 관례에 맞춘다면, 같은 기본 구현 위에 프레임워크별 사용 표면을 더할 수 있다.
부록: 화면 해석과 패키지 운영
본편이 “프레임워크 밖에서 동작하는 UI를 어떻게 나눌 것인가”를 다룬다면, 부록은 그 UI에 무엇을 보여 주고 어떻게 배포할지를 다룬다. 값보다 메타데이터가 중요한 Form Devtools는 값만으로 설명되지 않는 dirty, touched, modified, 포커스, 오류, 제출 상태와 배열 키를 진단 정보로 해석하고, 민감한 값을 렌더링 전에 가리는 기준을 정리한다.
개발 도구를 패키지로 배포할 때 정해야 하는 것은 패키지 진입점과 Custom Element 등록을 분리한다. exports와 sideEffects로 등록 경계를 선언하고, 개발 조건의 동적 import와 실제 프로덕션 빌드로 번들 포함 여부를 확인한다. 구현이 프레임워크 밖에 있어도 패키지가 무조건 애플리케이션에 들어오면 경계는 아직 끝난 것이 아니다.
추천 읽기 순서
처음 읽는다면 본편을 순서대로 읽는 편이 좋다. 관찰 계약이 입력의 모양을 정하고, Custom Element가 생명주기를 맡으며, Shadow DOM과 Lit이 각각 격리와 렌더링을 담당한 뒤에야 React 어댑터가 왜 얇아야 하는지 설명할 수 있기 때문이다. 앞의 경계를 건너뛰면 @lit/react가 무엇을 해 주는지는 보여도 왜 그 정도만 해야 하는지는 잘 보이지 않는다.
이미 특정 문제가 있다면 필요한 지점부터 읽어도 된다. 프레임워크 결합을 줄이고 싶다면 관찰 계약부터, 애플리케이션 CSS와 Devtools UI가 충돌한다면 Shadow DOM부터, Custom Element 상태를 화면에 반영하는 일이 번거롭다면 Lit부터 시작하면 된다. FormState를 어떤 정보 계층으로 보여 줄지 고민할 때는 부록 A를, 배포와 프로덕션 제외 정책이 필요할 때는 부록 B를 함께 읽으면 된다.
이 시리즈를 읽을 때 조심할 점
이 구조가 모든 개발 도구를 Web Component와 Lit으로 만들어야 한다는 뜻은 아니다. 하나의 프레임워크 안에서만 쓰이고 그 프레임워크의 Context나 개발자 도구 프로토콜을 깊게 활용해야 한다면 전용 구현이 더 자연스럽다. 이 시리즈에서 Web Component가 유효했던 이유는 여러 프레임워크가 같은 코어의 Form<TValues>와 관찰 계약을 공유한다는 조건이 먼저 있었기 때문이다.
반대로 “Web Component니까 자동으로 프레임워크 독립적이다”라고 생각해도 곤란하다. 요소 내부에서 React Context를 찾거나 Vue의 반응성을 직접 구독한다면 태그만 Custom Element일 뿐 핵심 구현은 여전히 특정 프레임워크에 묶여 있다. 중요한 것은 어떤 기술로 감쌌는지가 아니라, 상태의 소유권과 구독의 책임을 어느 경계에 남겼느냐이다.
Form Devtools가 읽기 전용이라는 조건도 같은 이유에서 중요하다. 상태를 관찰하는 도구가 Form을 수정하기 시작하면 관찰 계약은 명령 계약으로 넓어지고, 프레임워크별 업데이트 규칙과 검증 흐름까지 알아야 한다. 지금의 구조는 할 수 있는 일을 늘려서가 아니라, 하지 않을 일을 분명히 해서 유지된다.
코드와 현재 상태
완성된 코드는 ayden94/ilokesto-form-devtools에서 확인할 수 있다. 시리즈는 커밋 1f4690f8b4c500999c27ab419079557742181042과 패키지 버전 0.1.0을 기준으로 작성했다.
현재 소스는 GitHub에 공개되어 있지만 npm에는 배포하지 않았다. 글에 나오는 import와 설치 예시는 공개 패키지 사용 안내라기보다 저장소에 있는 구현과 패키지 경계를 설명하기 위한 코드다.
이 시리즈가 마지막에 남기는 것은 프레임워크별 Devtools 여러 벌이 아니다. Form을 읽는 계약, 브라우저에서 살아가는 요소, 격리된 화면, 반응형 렌더링, 프레임워크별 사용 표면을 서로 바꿔 끼울 수 있게 나눈 경계다. 그 경계가 유지된다면 핵심 구현은 한 번만 고치고, 각 프레임워크에는 필요한 만큼의 얇은 연결만 남길 수 있다.
댓글
댓글을 불러오는 중...