글을 삭제하시겠습니까?

삭제한 글은 복구할 수 없습니다.

React에서 Web Component를 React 컴포넌트처럼 사용하기

작성일:2026.10.24|수정일:2026.11.03|조회수:5

React에서 Web Component를 React 컴포넌트처럼 사용하기

Form Devtools를 React에서 사용한다고 해서 폼 구독과 화면을 React로 다시 만들 필요는 없다. 이미 존재하는 <ilokesto-form-devtools>에 form을 넘기고, 요소가 보내는 이벤트를 받으면 된다. 여기서 React 계층이 할 일은 새로운 Devtools 구현이 아니라 서로 다른 사용 표면 사이의 간격을 메우는 것이다.

React 19는 이 경계를 꽤 얇게 만들었다. 객체와 배열을 Custom Element의 프로퍼티로 전달할 수 있고, Custom Event에도 JSX에서 바로 리스너를 연결할 수 있다. 다만 런타임이 요소를 이해하는 것과 TypeScript가 프로젝트의 JSX를 이해하는 것은 다른 문제다. 현재 패키지가 제공하는 @lit/react 래퍼의 역할도 바로 그 차이에 있다.

React 19는 요소 인스턴스의 프로퍼티를 찾는다

React 19의 클라이언트 렌더링은 Custom Element에 prop을 적용할 때 같은 이름의 프로퍼티가 요소 인스턴스에 있는지 확인한다. 프로퍼티가 있으면 값을 그대로 대입하고, 없으면 HTML 속성으로 처리한다. 문자열로 만들 수 없는 값이라면 무조건 특별 취급하는 방식이 아니라, 요소가 어떤 프로퍼티를 실제로 제공하는가가 기준이다.

IlokestoFormDevtoolsElement의 공개 입력 가운데 form, open, position, maskPaths는 요소 프로퍼티로 준비된다. 따라서 클라이언트에서 form 객체와 maskPaths 배열은 문자열로 직렬화되지 않고 같은 자바스크립트 값으로 전달된다. 현재 React 테스트도 래퍼를 거치지 않은 React.createElement() 호출에서 element.form === form을 확인한다.

TSX
const element = React.createElement('ilokesto-form-devtools', {  form,  open: true,  maskPaths: ['password'],});

이 규칙은 클라이언트 렌더링에 대한 설명이다. React 19 공식 발표에 따르면 서버 렌더링에서는 문자열·숫자·true 같은 원시 값만 속성으로 출력하고, 객체·함수·false 같은 값은 마크업에서 생략한다. 그러므로 서버가 만든 HTML만 보고 form 객체가 전달되었다고 판단해서는 안 된다. 객체 프로퍼티는 클라이언트가 요소 인스턴스를 다루는 시점에 확인해야 한다.

이벤트도 직접 연결할 수 있다. React DOM의 Custom Element 문서가 설명하는 이벤트 prop은 실제 이벤트 이름 앞에 on을 붙이며, 이벤트 이름의 대소문자와 하이픈을 보존한다. 요소가 발생시키는 이름이 open-change이므로 직접 JSX에서 사용하는 이름은 onopen-change다.

직접 JSX의 남은 빈칸은 TypeScript가 채운다

브라우저와 React 런타임이 <ilokesto-form-devtools>를 렌더링할 수 있어도 TypeScript가 자동으로 이 태그의 prop을 아는 것은 아니다. 패키지 루트는 DOM 조회를 위한 HTMLElementTagNameMap을 보강하지만, React의 JSX.IntrinsicElements는 보강하지 않는다. 즉 현재 패키지가 직접 JSX의 타입까지 제공한다고 말하면 과장이다.

직접 태그를 쓰는 애플리케이션은 다음처럼 JSX 타입을 연결할 수 있다. DetailedHTMLProps를 사용한 이유는 일반 HTML prop뿐 아니라 IlokestoFormDevtoolsElement를 가리키는 ref 타입도 함께 얻기 위해서다. 요소 고유 입력은 공개 프로퍼티에서 고르고, 이벤트는 패키지가 내보내는 FormDevtoolsOpenChangeEvent로 따로 선언한다.

TS
// ilokesto-form-devtools.d.tsimport type * as React from 'react';import type {  FormDevtoolsOpenChangeEvent,  IlokestoFormDevtoolsElement,} from '@ilokesto/form-devtools';type ElementProps = React.DetailedHTMLProps<  React.HTMLAttributes<IlokestoFormDevtoolsElement>,  IlokestoFormDevtoolsElement> &  Partial<    Pick<      IlokestoFormDevtoolsElement,      'form' | 'open' | 'position' | 'maskPaths'    >  > & {    'onopen-change'?: (      event: FormDevtoolsOpenChangeEvent,    ) => void;  };declare module 'react' {  namespace JSX {    interface IntrinsicElements {      'ilokesto-form-devtools': ElementProps;    }  }}

요소 등록을 마친 브라우저 경계에서 이 선언을 포함하면 직접 JSX도 객체 프로퍼티, 이벤트 상세 타입, 요소 ref를 함께 표현할 수 있다.

TSX
import { useRef } from 'react';import type {  FormDevtoolsSource,  IlokestoFormDevtoolsElement,} from '@ilokesto/form-devtools';export function LoginFormDevtools({  form,}: {  form: FormDevtoolsSource;}) {  const devtoolsRef = useRef<IlokestoFormDevtoolsElement>(null);  return (    <ilokesto-form-devtools      ref={devtoolsRef}      form={form}      maskPaths={['password']}      position="bottom-right"      onopen-change={(event) => {        console.log(event.detail.open);      }}    />  );}

event는 React의 합성 이벤트로 바뀐 값이 아니라 요소가 보낸 CustomEvent<{ open: boolean }>다. 직접 JSX를 선택하면 런타임 우회 코드를 작성하는 비용은 없지만, 애플리케이션이 이 선언과 DOM 이벤트 이름을 소유해야 한다.

래퍼는 프로퍼티와 이벤트 이름만 대응시킨다

여러 React 애플리케이션에 같은 선언을 반복하고 싶지 않다면 래퍼가 그 타입 경계를 대신 소유할 수 있다. 현재 src/react.ts는 요소 클래스의 프로퍼티 접근자를 준비한 다음 @lit/react의 createComponent()에 요소 클래스, 태그 이름, 이벤트 대응표를 넘긴다. 핵심 매핑만 남기면 다음과 같다.

TS
IlokestoFormDevtoolsElement.prepareProperties();export const FormDevtools = createComponent({  tagName: ILOKESTO_FORM_DEVTOOLS_TAG,  elementClass: IlokestoFormDevtoolsElement,  react: React,  events: {    onOpenChange:      'open-change' as EventName<FormDevtoolsOpenChangeEvent>,  },});

createComponent()가 새로 만드는 것은 FormDevtools라는 React 컴포넌트 표면이다. 요소 프로퍼티를 React props로 노출하고, DOM 이벤트 이름 open-change를 onOpenChange에 연결한다. EventName<FormDevtoolsOpenChangeEvent> 캐스트 덕분에 콜백의 event.detail.open은 boolean으로 추론된다.

반환 타입에는 RefAttributes<IlokestoFormDevtoolsElement>도 포함된다. 그래서 래퍼의 ref 역시 React 컴포넌트 인스턴스나 별도 핸들이 아니라 실제 Custom Element를 가리킨다.

TSX
import { useRef } from 'react';import type {  FormDevtoolsSource,  IlokestoFormDevtoolsElement,} from '@ilokesto/form-devtools';import { FormDevtools } from '@ilokesto/form-devtools/react';export function LoginFormDevtools({  form,}: {  form: FormDevtoolsSource;}) {  const devtoolsRef = useRef<IlokestoFormDevtoolsElement>(null);  return (    <FormDevtools      ref={devtoolsRef}      form={form}      maskPaths={['password']}      position="bottom-right"      onOpenChange={(event) => {        console.log(event.detail.open);      }}    />  );}

겉으로는 일반 React 컴포넌트지만 렌더링 결과는 여전히 <ilokesto-form-devtools>다. 래퍼는 form을 React state로 복사하지 않고, open-change의 detail도 다른 모양으로 바꾸지 않는다. 이름과 타입을 React 쪽 관례에 맞출 뿐이다.

테스트는 경계에서 값이 보존되는지만 확인한다

현재 test/react.test.tsx에는 세 가지 경계 테스트가 있다. 래퍼에 넘긴 form이 실제 요소의 form과 같은 참조인지, 래퍼 없이 React 19가 객체 prop을 같은 요소 프로퍼티에 대입하는지, maskPaths 배열과 open-change 이벤트가 래퍼를 지나며 보존되는지를 확인한다.

이 가운데 첫 번째 테스트는 원본 폼의 값을 바꾼 뒤 같은 요소의 화면에 변경 결과가 나타나는 데까지 확인한다. React 래퍼가 별도 상태 모델을 만들지 않았다는 근거다. 이벤트 테스트도 onOpenChange가 한 번 호출되고 event.detail이 { open: true }인지 확인할 뿐, 이벤트 내용을 React용 값으로 다시 가공하지 않는다.

TSX
const maskPaths = ['password'] as const;const onOpenChange = vi.fn();root.render(  <FormDevtools    form={form}    maskPaths={maskPaths}    onOpenChange={onOpenChange}  />,);expect(element.maskPaths).toBe(maskPaths);launcher.click();expect(onOpenChange.mock.calls[0]?.[0].detail).toEqual({  open: true,});

반대로 현재 테스트가 직접 JSX의 onopen-change와 두 사용 방식의 ref를 명시적으로 검증한다고 말할 수는 없다. 직접 이벤트 연결은 React 19의 공개된 Custom Element 규칙에 기대고, ref 타입은 DetailedHTMLProps와 createComponent()의 반환 타입에서 확인된다. 패키지 테스트가 실제 ref 전달까지 회귀 방지해야 한다면 별도 테스트를 추가할 일이지, 이미 검증된 것처럼 쓰는 편이 낫지는 않다.

React 계층에는 사용 표면만 남긴다

직접 태그와 래퍼의 기능 차이는 거의 없다. 차이는 같은 요소를 어떤 이름과 타입으로 보여 주는가에 있다.

기준

React 19 직접 JSX

@lit/react 래퍼

렌더링 결과

<ilokesto-form-devtools>

<ilokesto-form-devtools>

객체·배열 입력

요소 프로퍼티로 전달

같은 요소 프로퍼티로 전달

이벤트 prop

onopen-change

onOpenChange

이벤트 객체

FormDevtoolsOpenChangeEvent

FormDevtoolsOpenChangeEvent

JSX 타입 소유자

애플리케이션

패키지의 래퍼

ref 대상

실제 Custom Element

실제 Custom Element

React 전용 상태·구독

없음

없음

한 애플리케이션이 JSX 보강을 직접 관리할 수 있고 DOM 이벤트 이름을 그대로 써도 괜찮다면 직접 태그로 충분하다. 여러 소비자에게 같은 prop 타입과 이벤트 이름을 제공하려면 래퍼가 낫다. 어느 쪽이든 React Context 탐색, 폼 상태 복제, 별도 구독과 화면 구현이 들어가기 시작하면 얇은 경계라는 전제는 깨진다.

결국 React 통합의 책임은 Devtools를 다시 만드는 일이 아니다. 기존 Custom Element의 프로퍼티, 이벤트, ref를 React의 사용 관례와 타입 체계에 맞춰 보여 주는 것, 지금은 거기까지로 충분하다.

하나의 구현, 프레임워크마다 다른 사용 표면

@lit/react라는 이름을 보면 @lit/vue와 @lit/svelte도 있을 것 같다. 하지만 현재 npm 레지스트리에는 그 이름의 공식 패키지가 없다. Lit이 안정된 프레임워크 래퍼로 제공하는 것은 @lit/react이고, Vue 쪽에는 Lit Labs의 실험 패키지인 @lit-labs/vue-utils와 @lit-labs/gen-wrapper-vue가 있다.

Vue 래퍼를 만들거나 생성하는 도구이기는 하지만, Lit Labs는 깨지는 변경이 생기거나 지원이 중단될 수도 있다고 명시한다. 따라서 이를 @lit/react와 같은 안정성의 @lit/vue라고 소개하는 것은 정확하지 않다. Svelte에는 이에 대응하는 공식 @lit/svelte나 Lit Labs 래퍼 생성기가 없다.

그렇다고 Vue와 Svelte에서 별도의 Devtools 구현이 필요한 것은 아니다. Vue 3의 Custom Element 지원은 요소 인스턴스에 프로퍼티가 있는지 확인한 뒤 값을 DOM 프로퍼티로 전달한다. <ilokesto-form-devtools>가 제공하는 form 같은 프로퍼티에는 객체를 그대로 넘길 수 있고, open-change도 Vue의 이벤트 문법으로 받을 수 있다. 빌드 설정에서 compilerOptions.isCustomElement로 이 태그가 Vue 컴포넌트가 아니라 Custom Element임을 알려 주면 다음과 같이 직접 사용한다.

VUE
<script setup lang="ts">import '@ilokesto/form-devtools/register';import type { FormDevtoolsSource } from '@ilokesto/form-devtools';defineProps<{ form: FormDevtoolsSource }>();</script><template>  <ilokesto-form-devtools    :form="form"    @open-change="event => console.log(event.detail.open)"  /></template>

Svelte도 소문자로 시작하는 Custom Element 태그를 DOM 요소로 다룬다. Svelte 5에서는 요소 프로퍼티와 on으로 시작하는 이벤트 속성을 연결할 수 있으므로, 같은 태그와 같은 open-change 이벤트를 그대로 사용한다.

SVELTE
<script lang="ts">import '@ilokesto/form-devtools/register';import type { FormDevtoolsSource } from '@ilokesto/form-devtools';let { form } = $props<{ form: FormDevtoolsSource }>();function onOpenChange(event: CustomEvent<{ open: boolean }>) {  console.log(event.detail.open);}</script><ilokesto-form-devtools  {form}  onopen-change={onOpenChange}/>

직접 사용으로 충분하다면 어댑터는 필요 없다. 다만 여러 애플리케이션에 같은 타입과 이름을 제공하고 싶다면 Vue나 Svelte용 진입점을 추가할 수 있다. 그 진입점이 맡을 일은 요소 등록, 프로퍼티 전달, 이벤트 이름, 타입과 ref를 각 프레임워크의 관례에 맞춰 정리하는 것이다. Form 구독, FormState 해석, Shadow DOM, Lit 렌더링까지 다시 만들기 시작하면 어댑터가 아니라 두 번째 Devtools 구현이 된다.

현재 @ilokesto/form-devtools가 실제로 제공하는 프레임워크 전용 진입점은 ./react뿐이다. Vue와 Svelte 예시는 이미 배포된 래퍼를 소개하는 것이 아니라, 같은 Web Component 위에 어떤 사용 표면을 더할 수 있는지 보여 준다. 결국 확장 가능한 부분은 프레임워크별 껍데기이고, 유지해야 할 핵심 구현은 <ilokesto-form-devtools> 하나다.

댓글

댓글을 삭제하시겠습니까?

삭제한 댓글의 내용은 복구할 수 없습니다.

댓글을 불러오는 중...