브라우저에 Form Devtools를 등록하기
작성일:2026.10.24|수정일:2026.11.03|조회수:6

폼을 프레임워크 밖에서 관찰할 수 있다는 말만으로는 화면이 생기지 않는다. getState(), getValues(), subscribe()만 받는 관찰 계약을 만들었어도, 그 계약을 어느 UI의 수명에 연결할지는 따로 정해야 한다. React 컴포넌트에 놓으면 마운트와 언마운트에 맞춰 구독을 시작하고 끝낼 수 있지만, Vue나 Solid에서는 각자의 컴포넌트 수명에 맞는 연결을 다시 만들어야 한다.
Custom Element를 택한 이유는 새로운 템플릿 문법이 필요해서가 아니다. 브라우저가 요소의 등록과 DOM 연결·해제 수명을 알려 주므로, Form Devtools도 그 경계에 맞춰 구독을 시작하고 정리할 수 있기 때문이다. 내가 Custom Element에서 필요했던 것도 화려한 컴포넌트 기능이 아니라, 브라우저가 소유하는 이 두 경계였다.
태그와 생성자를 연결한다
Custom Element는 자바스크립트 클래스만으로 완성되지 않는다. 브라우저가 어떤 태그를 만났을 때 어느 생성자로 요소 객체를 만들어야 하는지 알아야 한다. 그 연결을 저장하는 곳이 CustomElementRegistry이고, 페이지에서는 window.customElements로 접근한다.
Form Devtools는 button이나 input의 기능을 늘린 요소가 아니라 ilokesto-form-devtools라는 독립된 태그다. 이런 형태를 autonomous custom element라고 한다. 내장 요소를 확장하는 customized built-in element와 달리, HTML에서는 별도의 is 속성 없이 다음처럼 쓴다.
<ilokesto-form-devtools></ilokesto-form-devtools>브라우저가 이 이름을 안다고 가정할 수는 없다. customElements.define()으로 태그 이름과 생성자를 먼저 연결해야 한다. Custom Element 이름에는 일반 HTML 태그와 구분할 수 있도록 하이픈이 들어가야 하고 대문자는 쓸 수 없다. ilokesto-form-devtools도 이 규칙을 따른 이름이다.
class FormDevtoolsElement extends HTMLElement {}customElements.define('ilokesto-form-devtools', FormDevtoolsElement);등록 뒤에 document.createElement('ilokesto-form-devtools')를 호출하면 브라우저는 연결된 생성자의 인스턴스를 반환한다. 등록 전에 문서에 같은 태그가 있었다면 define()이 실행되는 시점에 그 요소도 등록된 구현으로 업그레이드된다. 결국 외부에 드러나는 것은 클래스 이름이 아니라 태그 이름이고, 레지스트리가 둘 사이의 계약을 보관한다.
기준 구현은 이 등록을 src/define.ts의 함수로 감쌌다. 루트 진입점에서 클래스를 import했다고 레지스트리까지 곧바로 바꾸지는 않는다.
import { IlokestoFormDevtoolsElement } from './IlokestoFormDevtoolsElement';export const ILOKESTO_FORM_DEVTOOLS_TAG = 'ilokesto-form-devtools';export function defineIlokestoFormDevtools( tagName = ILOKESTO_FORM_DEVTOOLS_TAG,): typeof IlokestoFormDevtoolsElement { const existing = customElements.get(tagName); if (existing) { if ( existing === IlokestoFormDevtoolsElement || existing.prototype instanceof IlokestoFormDevtoolsElement ) { return existing as typeof IlokestoFormDevtoolsElement; } throw new Error( `Cannot register ${tagName}: the tag is already registered by another Custom Element.`, ); } if (tagName === ILOKESTO_FORM_DEVTOOLS_TAG) { customElements.define(tagName, IlokestoFormDevtoolsElement); return IlokestoFormDevtoolsElement; } class AliasedIlokestoFormDevtoolsElement extends IlokestoFormDevtoolsElement {} customElements.define(tagName, AliasedIlokestoFormDevtoolsElement); return AliasedIlokestoFormDevtoolsElement;}customElements.get(tagName)은 그 이름으로 등록된 생성자를 돌려준다. 아무것도 등록되지 않았다면 undefined다. 따라서 defineIlokestoFormDevtools()는 먼저 현재 레지스트리를 읽고, 등록해도 되는 상황인지 판단한 뒤 define()을 호출한다.
반복 등록과 충돌을 구분한다
customElements.define()에 이미 사용 중인 태그 이름을 다시 넘기면 브라우저는 NotSupportedError를 던진다. 애플리케이션 초기화 코드가 두 번 실행되거나 여러 모듈이 같은 등록 함수를 부를 수 있으므로, 반복 호출 자체를 모두 실패로 만들 필요는 없다. 그래서 같은 구현이 이미 등록되어 있으면 기존 생성자를 그대로 반환한다.
하지만 이름이 같다는 이유만으로 모든 중복을 무시하면 다른 문제가 생긴다. 전혀 관계없는 요소가 ilokesto-form-devtools를 먼저 차지했는데도 성공한 것처럼 넘어가면, 호출자는 자신이 요청한 구현이 등록됐다고 오해한다. 기준 구현이 사용하는 window.customElements는 페이지 전역 상태이고, 등록된 정의는 해제하거나 다른 생성자로 교체할 수도 없다. 기준 구현이 다른 생성자와의 충돌을 오류로 드러내는 이유다.
별칭에는 한 가지 규칙이 더 걸린다. customElements.define()은 같은 태그 이름뿐 아니라 이미 등록에 사용한 생성자를 다른 이름으로 다시 등록할 때도 NotSupportedError를 던진다. 따라서 다음 코드는 허용되지 않는다.
customElements.define( 'ilokesto-form-devtools', IlokestoFormDevtoolsElement,);customElements.define( 'company-form-devtools', IlokestoFormDevtoolsElement,); // NotSupportedError기준 구현은 별칭마다 IlokestoFormDevtoolsElement를 상속한 새 생성자를 만든다. company-form-devtools와 기본 태그가 같은 동작 계보를 공유하면서도, 레지스트리에는 서로 다른 생성자가 들어간다. 같은 별칭으로 함수를 다시 호출하면 앞서 등록한 하위 클래스가 기준 구현의 인스턴스인지 확인하고 그 생성자를 반환한다.
이 방어가 패키지의 모든 버전 조합을 호환시켜 주는 것은 아니다. 서로 다른 번들에 포함된 두 클래스는 코드가 같아 보여도 자바스크립트에서는 다른 생성자일 수 있고, 상속 관계도 공유하지 않을 수 있다. 이 함수가 안전하게 반복할 수 있다고 판단하는 범위는 같은 생성자 또는 그 하위 클래스까지다. 반복 등록과 이름 충돌은 닮았지만 같은 문제가 아니다.
등록은 함수 호출이 결정한다
레지스트리를 바꾸는 일은 페이지 전체에 영향을 주는 부수 효과다. 그래서 기준 구현의 등록 함수는 이름을 내보내는 모듈을 읽었다는 이유만으로 자동 실행되지 않는다. 호출자가 defineIlokestoFormDevtools()를 실행했을 때 비로소 현재 페이지의 레지스트리가 바뀐다.
import { defineIlokestoFormDevtools } from '@ilokesto/form-devtools';defineIlokestoFormDevtools();여기서 중요한 것은 등록 시점이 코드에 드러난다는 점이다. 패키지가 이 명시적 호출과 import만으로 등록하는 경로를 어떻게 나누는지는 배포 계약의 문제이므로 뒤에서 따로 다룬다. 이 편에서는 브라우저 레지스트리를 바꾸는 사건이 함수 호출이라는 경계까지만 남긴다.
객체는 Attribute가 아니라 Property로 건넨다
태그를 등록했다고 <ilokesto-form-devtools form="...">에 Form 인스턴스를 넣을 수 있는 것은 아니다. HTML Attribute는 마크업에 기록되는 문자열 경계다. setAttribute('form', value)에 어떤 값을 넘겨도 브라우저가 보관하는 Attribute 값은 문자열이고, getAttribute('form')도 문자열 또는 null을 돌려준다.
Property는 요소 객체에 있는 자바스크립트 값이다. 객체, 함수, 배열처럼 문자열로 바꾸면 의미를 잃는 값도 그대로 가질 수 있다. Form Devtools가 받는 Form은 getState(), getValues(), subscribe() 메서드와 객체 동일성을 가진 살아 있는 인스턴스이므로 Property로 전달해야 한다. JSON으로 직렬화해 Attribute에 넣으면 메서드도 사라지고, 어느 Form을 구독하는지 구분하는 동일성도 사라진다.
기준 구현이 요구하는 입력도 전체 Form 클래스가 아니라 관찰에 필요한 세 메서드뿐이다.
// src/types.tsimport type { Form } from '@ilokesto/form';export type FormDevtoolsSource<TValues = unknown> = Pick< Form<TValues>, 'getState' | 'getValues' | 'subscribe'>;브라우저가 같은 이름의 Attribute와 Property를 자동으로 같은 값으로 맞춰 주는 것도 아니다. 일부 내장 요소는 input.value처럼 자체 규칙에 따라 둘을 연결하고, Custom Element 작성자도 observedAttributes와 attributeChangedCallback()으로 변환 규칙을 만들 수 있다. 하지만 임의의 객체를 위한 변환은 브라우저의 기본 동작이 아니다. <ilokesto-form-devtools form="login">이라는 문자열 Attribute와 devtools.form = loginForm이라는 객체 Property는 별개의 입력이다.
실제 연결 순서는 태그를 정의하고, 생성된 요소 객체에 Form을 대입한 뒤, 문서에 붙이는 것이다.
import { CreateForm } from '@ilokesto/form';import { defineIlokestoFormDevtools, ILOKESTO_FORM_DEVTOOLS_TAG, type IlokestoFormDevtoolsElement,} from '@ilokesto/form-devtools';const form = new CreateForm({ defaultValues: { email: '', password: '', },});defineIlokestoFormDevtools();const devtools = document.createElement( ILOKESTO_FORM_DEVTOOLS_TAG,) as IlokestoFormDevtoolsElement;devtools.form = form;document.body.append(devtools);document.createElement()가 반환한 것은 등록된 생성자의 인스턴스다. 따라서 Form을 넘기는 일도 특정 UI 프레임워크의 props 전달이 아니라 DOM 요소의 Property 대입이다. 프레임워크별 어댑터가 필요하더라도 마지막에 이 동작으로 번역할 수 있다면, Form Devtools 요소 자체는 하나로 남는다.
DOM 연결 동안만 구독한다
생성자 호출과 DOM 연결은 같은 사건이 아니다. document.createElement()로 요소를 만들었어도 아직 문서에는 붙지 않았을 수 있다. 반대로 한 번 제거한 요소 객체를 나중에 다시 붙일 수도 있다. 생성자는 요소 인스턴스를 만들 때 실행되지만, [connectedCallback()과 disconnectedCallback()](https://developer.mozilla.org/en-US/docs/Web/API/Web_components/Using_custom_elements#custom_element_lifecycle_callbacks)은 그 인스턴스와 문서의 연결이 바뀔 때마다 실행될 수 있다.
이 차이는 외부 Form 구독과 바로 이어진다. 요소를 만든 순간부터 구독하면 화면에 붙지 않은 요소도 계속 상태 변경을 받는다. DOM에서 제거됐는데 구독 해제 함수를 호출하지 않으면 Form 쪽에는 더 이상 쓰지 않는 콜백이 남는다. 브라우저는 연결과 해제 시점을 알려 줄 뿐, Form의 subscribe()가 반환한 함수를 대신 호출해 주지는 않는다.
다음 코드는 이 관계만 보이기 위해 브라우저 표준 API로 줄인 예다. 실제 Form Devtools 구현을 그대로 옮긴 코드가 아니며, 화면을 그리는 세부 동작과 연결된 상태에서 form Property가 바뀌는 경우는 일부러 제외했다.
type FormSource = { getState(): unknown; subscribe(listener: () => void): () => void;};class FormDevtoolsElement extends HTMLElement { form?: FormSource; #unsubscribe?: () => void; connectedCallback(): void { this.#disconnectForm(); if (!this.form) { return; } const form = this.form; const readSnapshot = (): void => { const snapshot = form.getState(); this.textContent = JSON.stringify(snapshot, null, 2); }; readSnapshot(); this.#unsubscribe = form.subscribe(readSnapshot); } disconnectedCallback(): void { this.#disconnectForm(); } #disconnectForm(): void { this.#unsubscribe?.(); this.#unsubscribe = undefined; }}connectedCallback()은 먼저 과거 구독을 정리한다. 현재 form이 있으면 스냅숏을 한 번 읽고, 이후 변경을 받기 위해 구독한다. 콜백 안에서 this.form을 매번 다시 읽지 않고 지역 변수 form을 캡처했으므로, 이 콜백은 자신이 실제로 구독한 인스턴스에서 상태를 읽는다.
disconnectedCallback()은 요소를 폐기하는 소멸자가 아니다. 같은 요소가 다시 연결될 수 있으므로, 문서 밖에서 유지할 필요가 없는 외부 관계만 끊는다. 다시 붙으면 connectedCallback()이 다시 실행되고 현재 Form과 새 구독을 만든다. 요소 객체의 생존 기간과 활성 구독의 기간은 겹치지만 같지는 않다.
중요한 것은 콜백 이름 자체보다 책임의 경계다. 브라우저는 요소가 문서에 연결됐는지 알려 주고, Form은 구독 해제 함수를 돌려주며, Custom Element는 둘이 연결된 동안만 그 함수를 보관한다. 화면이 최신 상태인지 확인하는 것과 제거 뒤 콜백이 남지 않았는지 확인하는 것도 다른 일이다. 전자는 렌더링 결과로 볼 수 있지만, 후자는 구독 해제 함수가 호출됐는지 따로 검증해야 한다.
DOM 연결 콜백이 알려 주지 않는 것
요소가 문서에 붙어 있는 동안 devtools.form을 다른 Form 인스턴스로 바꿔도 DOM 연결 상태는 변하지 않는다. 따라서 브라우저는 connectedCallback()이나 disconnectedCallback()을 다시 호출하지 않는다. 이전 Form 구독을 끊고 새 Form을 구독하는 일은 DOM 연결 수명과는 별도의 Property 변경 문제다.
기준 구현은 이 경우도 처리하지만, 그 방법까지 끌어오면 Custom Element의 플랫폼 수명과 화면 갱신 도구의 규칙이 한꺼번에 섞인다. 여기서는 경계만 남겨 두는 편이 낫다. DOM 연결 콜백은 요소가 문서 안팎으로 이동한 사실을 알려 줄 뿐, 임의의 Property 대입을 관찰하는 장치는 아니다.
Custom Element를 두었다고 프레임워크 독립성이 저절로 생기지는 않는다. 등록은 window.customElements라는 페이지 전역 레지스트리를 다루고, 객체 입력은 Attribute가 아닌 Property로 건네야 하며, 외부 구독은 DOM 연결 상태에 맞춰 직접 정리해야 한다. 내가 Custom Element에서 중요하다고 보는 부분도 태그 문법보다 이 책임 배치다. 브라우저가 태그와 연결 시점을 소유하고, 호출자가 Form 객체를 소유하며, 요소는 그 둘이 만나는 동안의 구독만 소유한다.
이제 Devtools는 어느 컴포넌트 트리에도 들어갈 수 있는 브라우저 요소가 됐다. 하지만 독립된 태그를 얻었다고 내부 DOM과 CSS까지 저절로 격리되는 것은 아니다. 문서의 전역 스타일과 Devtools 내부 구조가 서로 침범하지 않게 하려면, Shadow DOM은 어디에 경계를 만들고 무엇을 그 경계 밖에 남겨야 할까?
댓글
댓글을 불러오는 중...