[번역] 타입 세이프한 합성 컴포넌트 만들기

Front-End•2026.01.03

원문: https://tkdodo.eu/blog/building-type-safe-compound-components

Dominik - 2024년 1월 22일

#1: 디자인 시스템 설계하기

#2: 툴팁 컴포넌트는 존재해서는 안 된다

#3: 타입 안전한 합성 컴포넌트 구축하기

저는 컴포넌트 라이브러리를 구축할 때 합성 컴포넌트(Compound components) 패턴이 정말 좋은 디자인 패턴이라고 생각합니다. 이 패턴은 모든 변형을 하나의 프롭(Prop)이 가득한 API로 강제하지 않으면서도, 사용자가 컴포넌트를 구성하는 방식에 유연성을 제공합니다. 또한, 마크업에서 컴포넌트 간의 관계를 명시적으로 만들어 줍니다.

그렇다고 해서 합성 컴포넌트가 항상 적합하다는 뜻은 아닙니다. 때로는 props를 사용하는 것이 더 나을 때도 있습니다.

나쁜 예시

합성 컴포넌트와 관련하여 흔히 볼 수 있는 예시는 Options를 포함한 Select입니다. 아마도 HTML에서 작동하는 방식과 유사하기 때문일 것입니다.

// Compound-Select
import { Select, Option } from '@/components/select'
function ThemeSwitcher({ value, onChange }) {
  return (
    <Select value={value} onChange={onChange}>
      <Option value="system">🤖</Option>
      <Option value="light">☀️</Option>
      <Option value="dark">🌑</Option>
    </Select>
  )
}

제가 이 예시가 합성 컴포넌트의 장점을 보여주기에 이상적이지 않다고 생각하는 몇 가지 이유가 있습니다.

1. 고정된 레이아웃

합성 컴포넌트는 사용자가 children을 원하는 대로 배치할 수 있게 해줄 때 빛을 발합니다. Select의 경우, 우리는 아마 그런 기능이 필요하지 않을 것입니다. options는 메뉴 안으로 들어가고, 우리는 각 옵션을 차례대로 보여주고 싶어 합니다. 이것이 바로 많은 사람들이 타입 수준에서 children에 전달할 수 있는 내용을 제한하고 싶어 하는 이유입니다. 예를 들어 Select에는 Option만 전달할 수 있도록 하는 식입니다.

이는 현재로서는 불가능할 뿐만 아니라(해당 이슈는 2018년부터 열려 있습니다), 바람직하지도 않습니다. 이 글에서 합성 컴포넌트를 타입 안전하게 만드는 방법을 알려주길 기대하셨을 텐데, 실제로 알려드릴 것입니다. 다만 그것은 children에 관한 것이 전혀 아닙니다. 제 의견은 만약 children을 특정 타입으로 제한하고 싶다면, 합성 컴포넌트는 잘못된 추상화라는 것입니다.

2. 동적 콘텐츠

합성 컴포넌트는 콘텐츠가 대부분 정적일 때 정말 유용합니다. 위의 예시는 하드코딩된 세 개의 옵션이 있으니 적합해 보이죠?

현실적으로 우리는 단 세 개의 옵션만 있는 Select를 사용하지 않을 가능성이 높습니다. 콘텐츠는 대부분 동적 결과 집합을 가진 API 호출에서 올 것이기 때문입니다. 또한, 대부분의 디자인 가이드는 다섯 개 미만의 옵션에는 Select를 사용하지 말 것을 권장합니다. 드롭다운 안에 적은 수의 선택지를 숨기는 것은 불필요한 클릭과 인지 부하를 유발하기 때문입니다.

실제로 Adverity에서 우리는 합성 컴포넌트 방식의 Select로 시작했다가, 대부분의 사용 사례에서 다음과 같은 매핑 코드를 작성해야 했습니다.

// Select-Usage
import { Select, Option } from '@/components/select'
function UserSelect({ value, onChange }) {
  const userQuery = useSuspenseQuery(userOptions)
  return (
    <Select value={value} onChange={onChange}>
      {userQuery.data.map((option) => (
        <Option value={option.value}>{option.label}</Option>
      ))}
    </Select>
  )
}

이 시점에서 우리는 children 대신 props를 사용하는 Select를 노출하는 방식으로 전환했습니다.

// Select-With-Options
import { Select } from '@/components/select'
function UserSelect({ value, onChange }) {
  const userQuery = useSuspenseQuery(userOptions)
  return (
    <Select
      value={value}
      onChange={onChange}
      options={userQuery.data}
    />
  )
}

이를 통해 도처에서 해야 했던 지루한 매핑 작업을 없앨 수 있었을 뿐만 아니라, 제한해야 할 children이 없었기에 우리가 원하던 타입 안전성도 얻을 수 있었습니다. 또한, Select를 제네릭(Generic)으로 만들어 value, onChange, options가 모두 동일한 타입을 갖도록 보장할 수 있습니다.

// SelectProps
type SelectValue = string | number
type SelectOption<T> = { value: T; label: string }
type SelectProps<T extends SelectValue> = {
  value: T
  onChange: (value: T) => void
  options: ReadonlyArray<SelectOption<T>>
}

슬롯(Slots)

ModalDialog 컴포넌트는 사용자에게 컴포넌트 합성의 모든 권한을 주고 싶지 않은 또 다른 예시입니다. 제 말은, DialogFooter를 DialogHeader 위에 렌더링하는 것은 말이 되지 않는다는 것입니다. 또한 누군가 실수로 DialogBackdrop을 빠뜨리거나 DialogBody와 DialogFooter 사이에 서로 다른 간격을 만드는 것도 원치 않습니다. 일관성과 순서가 중요한 경우, 슬롯(Slots)이 대개 더 나은 추상화입니다.

// ModalDialog
function ModalDialog({ header, body, footer }) {
  return (
    <DialogRoot>
      <DialogBackdrop />
      <DialogContent>
        <DialogHeader>{header}</DialogHeader>
        <DialogBody>{body}</DialogBody>
        <DialogFooter>{footer}</DialogFooter>
      </DialogContent>
    </DialogRoot>
  )
}
// 사용법:
<ModalDialog header="Hello" body="World" />

슬롯은 여전히 특정 위치에 임의의 React 컴포넌트를 주입할 수 있게 하여 어느 정도의 유연성을 제공하면서도, 아무도 그 상용구(Boilerplate) 코드를 도처에 복사-붙여넣기 하지 않아도 되도록 보장합니다. 디자인 시스템 내부에 이러한 Dialog 기본 요소(Primitives)를 갖추는 것은 물론 훌륭하지만, 저는 이를 사용자에게 직접 노출하지는 않을 것입니다.

이 두 가지 지표, 즉 고정된 레이아웃과 대부분 동적인 콘텐츠는 우리가 정말로 합성 컴포넌트를 원하는지 의문을 갖게 만듭니다. 그렇다면 언제 정말로 적합할까요? 그리고 그것이 타입 안전성과 무슨 상관이 있을까요?

더 나은 예시

대부분 고정된 요소들을 가지면서 동적인 레이아웃의 자식 요소들로부터 이점을 얻을 수 있는 좋은 사례는 <ButtonGroup>, <TabBar> 또는 <RadioGroup>입니다.

// RadioGroup
import { RadioGroup, RadioGroupItem } from '@/components/radio'
import { Flex } from '@/components/layout'
function ThemeSwitcher({ value, onChange }) {
  return (
    <RadioGroup value={value} onChange={onChange}>
      <Flex direction={['row', 'column']} gap="sm">
        <RadioGroupItem value="system">🤖</RadioGroupItem>
        <RadioGroupItem value="light">☀️</RadioGroupItem>
        <RadioGroupItem value="dark">🌑</RadioGroupItem>
      </Flex>
    </RadioGroup>
  )
}

Select와의 주요 차이점은 우리가 명시적으로 RadioGroupItem 타입이 아닌 children을 갖고 싶어 한다는 것입니다. 이를 원하는 대로 배치하고, 어쩌면 추가적인 도움말 텍스트까지 넣을 수 있는 능력은 필수적입니다. 물론 RadioGroup에 동적인 옵션이 필요한 경우도 있겠지만, 그런 경우에는 앞서 보여드린 것처럼 루프를 만드는 것이 세상이 끝날 일은 아닙니다.

여전히 타입 안전성 문제가 남습니다. ThemeSwitcher에 전달된 value가 단순한 문자열이 아니라 문자열 리터럴(String literal)이길 바라기 때문입니다.

type ThemeValue = 'system' | 'light' | 'dark'

RadioGroup을 앞서 보여드린 것처럼 제네릭으로 만들면 value와 onChange 프롭을 ThemeValue에 묶을 수 있지만, RadioGroupItem은 어떨까요? 각 아이템에 전달된 value가 정적으로 분석될 수 있도록 어떻게 보장할 수 있을까요?

타입 안전성

물론 RadioGroupItem도 제네릭으로 만들 수 있습니다. 하지만 이 접근 방식의 문제는 JSX 자식 요소가 부모 컴포넌트로부터 타입 매개변수를 "상속"받지 않기 때문에, RadioGroup의 타입이 아이템에서 자동으로 사용 가능하지 않다는 점입니다. 따라서 RadioGroup이 완벽하게 타입 정의되어 <ThemeValue>를 추론하더라도, 우리는 여전히 각 RadioGroupItem에 매개변수를 지정해야 합니다.

// Generic-RadioGroupItem
import { RadioGroup, RadioGroupItem } from '@/components/radio'
import { Flex } from '@/components/layout'
type ThemeValue = 'system' | 'light' | 'dark'
type ThemeSwitcherProps = {
  value: ThemeValue
  onChange: (value: ThemeValue) => void
}
function ThemeSwitcher({ value, onChange }) {
  return (
    <RadioGroup value={value} onChange={onChange}>
      <Flex direction={['row', 'column']} gap="sm">
       <RadioGroupItem<ThemeValue> value="system">🤖</RadioGroupItem>
       <RadioGroupItem<ThemeValue> value="light">☀️</RadioGroupItem>
       <RadioGroupItem<ThemeValue> value="dark">🌑</RadioGroupItem>
      </Flex>
    </RadioGroup>
  )
}

이는 좋은 API가 아닙니다. 수동 타입 어노테이션(Type annotation)은 잊어버리기 쉽기 때문입니다. 저를 아시는 분들은 제가 가능하다면 항상 타입이 완전히 추론되는 것을 선호한다는 것을 아실 겁니다. 합성 컴포넌트를 위해 이를 수행하는 가장 좋은 방법은 해당 컴포넌트들을 직접 노출하지 않고, 사용자에게 호출할 메서드만 제공하는 것입니다.

컴포넌트 팩토리 패턴(Component Factory Pattern)

이 패턴의 정확한 명칭인지는 확실하지 않지만, 개념을 전달하기에는 충분하다고 생각합니다. 기본적으로 수동 타입 어노테이션을 완전히 없앨 수는 없지만, 이를 숨기고 명시적으로 만들 수는 있습니다. RadioGroup과 RadioGroupItem을 노출하는 대신, 타입 매개변수와 함께 한 번 호출해야 하는 createRadioGroup이라는 함수만 내보냅니다. 그러면 이 함수는 타입이 서로 묶인 정적 타입의 RadioGroup과 그에 대응하는 RadioGroupItem을 반환합니다.

// createRadioGroup
import { RadioGroup, RadioGroupItem } from './internal/radio'
export const createRadioGroup = <T extends GroupValue = never>(): {
  RadioGroup: (props: RadioGroupProps<T>) => JSX.Element
  RadioGroupItem: (props: Item<T>) => JSX.Element
} => ({ RadioGroup, RadioGroupItem })

이것은 런타임에서 내부의 RadioGroup과 RadioGroupItem을 객체로 감싸는 것 외에는 아무것도 하지 않습니다. 하지만 타입 수준에서는 타입 매개변수들을 서로 묶어줍니다. 그리고 제네릭의 기본값을 never로 설정했다는 것은 사용자가 결과물로 의미 있는 작업을 하기 위해 타입을 반드시 전달해야 함을 의미하며, 다음과 같이 사용할 수 있게 해줍니다.

// Typed-RadioGroup
import { createRadioGroup } from '@/components/radio'
import { Flex } from '@/components/layout'
type ThemeValue = 'system' | 'light' | 'dark'
type ThemeSwitcherProps = {
  value: ThemeValue
  onChange: (value: ThemeValue) => void
}
const Theme = createRadioGroup<ThemeValue>()
function ThemeSwitcher({ value, onChange }) {
  return (
    <Theme.RadioGroup value={value} onChange={onChange}>
      <Flex direction={['row', 'column']} gap="sm">
        <Theme.RadioGroupItem value="system">🤖</Theme.RadioGroupItem>
        <Theme.RadioGroupItem value="light">☀️</Theme.RadioGroupItem>
        <Theme.RadioGroupItem value="dark">🌑</Theme.RadioGroupItem>
      </Flex>
    </Theme.RadioGroup>
  )
}

물론 이 버전도 완벽하게 방어적인 것은 아닙니다. 여전히 다르게 타입 정의된 RadioGroup을 생성하고 그 아이템들을 Theme.RadioGroup에 전달할 수 있지만, 실수로 그런 일이 발생할 가능성은 훨씬 적습니다.

결론적으로, 이 접근 방식은 합성 컴포넌트를 훌륭하게 만드는 유연성을 유지하면서도 강력한 타입 보장을 추가합니다. 유일한 실질적인 비용은 사용자가 컴포넌트를 직접 임포트하지 않고, 대신 함수 호출을 통해 컴포넌트 패밀리의 타입이 지정된 인스턴스를 생성해야 한다는 점입니다. 저는 이것이 가치 있는 트레이드오프이며, 디자인 시스템 사용자들을 위해 합성 컴포넌트를 최대한 타입 안전하게 만드는 가장 좋은 방법이라고 생각합니다.