원문: https://github.com/facebook/astryx/wiki/RSC-Compatibility · 번역 기준: 2026-09-03

결정: React hook을 사용하는 모든 Astryx 컴포넌트는 'use client' directive를 포함해야 합니다.

관련 결정은 다음을 참고하십시오:

• Component Authoring Guide — 전체 authoring 컨벤션
• Distribution — 패키지, 버저닝, Astryx의 배포 방식
• RSC Utilities — 향후 server component 통합 패턴

배경

Astryx 컴포넌트는 런타임에 theme token을 소비하기 위해 useContext를 사용합니다(ThemeContext를 통해). 즉 theme이 적용되는 모든 컴포넌트는 React Server Components(RSC) 환경에서 본질적으로 client component입니다.

'use client' directive가 없으면, Server Component 파일에서 Astryx 컴포넌트를 import 하는 소비자는 혼란스러운 createContext / useState 에러를 만나게 됩니다. 해결 방법도 명확하지 않습니다 — 자신의 파일이 왜 client component여야 하는지 이해하려면 import 그래프를 추적해야 합니다.

이 마찰은 한 dogfooder가 보고했습니다: 렌더링을 위해 Text와 Badge를 import 하던 schema 파일이 page.tsx를 통해 Server Component로 끌려 들어갔고, 에러는 Astryx 내부 깊숙한 곳의 createContext를 가리켰습니다.

결정

packages/core/src/에서 React hook을 사용하는 모든 파일은 (앞머리 주석이 있다면 그 이후) 첫 번째 문장으로 'use client'를 가져야 합니다.

이 요구사항을 발동시키는 hook:

• useState, useEffect, useRef, useContext, useCallback, useMemo
• useId, useReducer, useLayoutEffect, useTransition, useImperativeHandle
• createContext (client 측 해석이 필요한 context를 생성)

directive가 필요 없는 파일:

• 순수 re-export barrel (index.ts)