Feature Flags

Lynx는 다양한 피쳐 플래그를 통해 CSS 엔진, 텍스트 렌더링, 레이아웃, 이벤트 처리 등의 동작을 제어합니다. SEED Design을 Lynx에서 사용할 때는 웹과의 동작 일관성을 위해 아래 플래그들을 활성화하는 것을 권장합니다.

플러그인 구조

Lynx의 피쳐 플래그는 두 개의 rsbuild 플러그인을 통해 설정합니다.

pluginLynxConfig에 설정한 값은 pluginReactLynx가 자동으로 읽어가므로, pluginLynxConfig 한 곳에서 모든 플래그를 관리하면 됩니다.

기본 활성화 플래그

pluginReactLynx를 사용하면 아래 플래그들이 기본적으로 켜져 있습니다. 별도 설정 없이도 이미 활성화되어 있지만, 명시적으로 pluginLynxConfig에도 넣어두는 것을 권장합니다.

enableCSSSelector

Lynx CSS를 기존 pseudo_map 기반 매칭이 아니라 LynxCSSSelector / RuleSet 기반의 새 selector 파이프라인으로 파싱하고 매칭합니다. 이 플래그는 CSS selector 엔진 경로를 켜는 옵션이지, Web에서 쓰는 모든 selector를 동일하게 지원한다는 의미는 아닙니다.

enableCSSInvalidation

RuleInvalidationSet을 사용한 선택적 스타일 재계산을 활성화합니다.

추가 필수 설정

pluginLynxConfig에서 추가로 활성화해야 하는 플래그들입니다.

CSS

enableCSSStrictMode

CSS 값 파싱을 웹 표준과 동일하게 엄격하게 적용합니다.

enableCSSInheritance

CSS 속성 상속을 활성화합니다.

enableCSSInlineVariables

JS에서 설정한 CSS 변수를 인라인 스타일처럼 처리합니다.

텍스트 & 레이아웃

enableTextRefactor

텍스트 렌더링을 웹 표준에 맞게 개선합니다.

fontScaleEffectiveOnlyOnSp

시스템 폰트 크기 설정의 영향 범위를 sp 단위로 제한합니다.

enableFixedNew

position: fixed 요소의 처리를 개선합니다.

enableFlexBasisZeroPercent

flex 축약 속성에서 생략된 flex-basis를 0%로 처리합니다 (웹 브라우저 동작과 동일).

상황별 설정

모든 프로젝트에 필수는 아니지만, 특정 기능을 사용할 때 활성화하면 좋은 플래그들입니다. 모두 pluginLynxConfig에서 설정합니다.

이벤트 & 제스처

enableNewGesture

Gesture Handler API를 활성화합니다.

enableEventHandleRefactor

이벤트 처리 로직을 리팩토링하여 동적 이벤트 리스너 등록을 지원합니다.

enablePlatformGesture

네이티브 플랫폼과 Lynx 간의 제스처 충돌을 해결합니다.

enableTransformedTouchPosition

transform이 적용된 요소에서 터치 좌표를 올바르게 계산합니다.

관찰 & 렌더링

enableNewIntersectionObserver

IntersectionObserver가 스크롤 이벤트 없이도 독립적으로 동작합니다.

enableVsyncAlignedFlush

VSync 신호에 맞춰 UI 업데이트를 동기화합니다.

unifyVWVHBehavior

vw/vh 단위가 뷰포트 변경에 따라 동적으로 재계산됩니다.

성능 최적화

enableCSSLazyImport

CSS import 규칙을 지연 디코딩합니다.

enableTextLayoutCache

텍스트 레이아웃 결과를 캐시하여 재사용합니다.

enableCSSClassMerge

중복되는 CSS 클래스를 빌드 시점에 병합합니다.

enableSimpleStyling

간소화된 스타일링 모듈을 사용합니다.

전체 권장 설정

import { defineConfig } from "@lynx-js/rspeedy";
import { pluginReactLynx } from "@lynx-js/react-rsbuild-plugin";
import { pluginLynxConfig } from "@lynx-js/config-rsbuild-plugin";

export default defineConfig({
  plugins: [
    pluginReactLynx(),
    pluginLynxConfig({
      // 기본 활성화이지만 명시적으로 설정
      enableCSSSelector: true,
      enableCSSInvalidation: true,

      // CSS
      enableCSSInheritance: true,
      enableCSSInlineVariables: true,
      // enableCSSStrictMode: false (CSS 속성 호환성 이슈로 비활성화 권장)

      // 텍스트 & 레이아웃
      enableTextRefactor: true,
      fontScaleEffectiveOnlyOnSp: true,
      enableFixedNew: true,
      enableFlexBasisZeroPercent: true,

      // 이벤트 (필요 시)
      // enableNewGesture: true,
      // enableEventHandleRefactor: true,
      // enablePlatformGesture: true,
      // enableTransformedTouchPosition: true,

      // 관찰 & 렌더링 (필요 시)
      // enableNewIntersectionObserver: true,
      // enableVsyncAlignedFlush: true,
      // unifyVWVHBehavior: true,

      // 성능 (필요 시)
      // enableCSSLazyImport: true,
      // enableTextLayoutCache: true,
    }),
  ],
});