Feature Flags

Lynx 플래그는 SEED의 스타일과 동작에 필요한 기능과 화면에 따라 선택하는 기능으로 나누어 설정하세요. 기능이 필요하더라도 플러그인이 이미 켜 주면 설정을 생략할 수 있습니다. 반대로 빌드 도구에서 옵션이 사라졌다고 엔진의 기능까지 제거된 것은 아닙니다.

SEED의 최소 지원 Lynx Engine은 3.6입니다. 이 문서는 엔진 버전을 올리도록 요구하는 대신, 각 플래그를 언제 유지하고 언제 지울 수 있는지 설명합니다.

최소 권장 설정

다음은 SEED의 CSS 상속, 인라인 변수, Dynamic/Static 타이포그래피, fixed 요소를 사용하는 앱의 기본 구성입니다. Selector와 Invalidation은 pluginReactLynx의 기본값을 사용합니다. 여러 손가락의 터치 정보를 사용하는 화면에서는 enableMultiTouch: true를 추가하세요. Pull To Refresh를 쓰는 앱은 pluginReactLynx에 enableNewGesture: true도 추가해야 합니다. 테마·모션 설정의 런타임 갱신은 아래 globalPropsMode 설명을 확인하세요.

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({
      engineVersion: "3.6", // 앱이 지원할 최소 Engine. 실제 실행 엔진을 바꾸지는 않습니다.
    }),
    pluginLynxConfig({
      enableCSSInheritance: true,
      enableCSSInlineVariables: true,
      fontScaleEffectiveOnlyOnSp: true,
      enableFixedNew: true,
    }),
  ],
});

예제의 옵션과 기본값은 다음 출시 패키지 조합을 기준으로 확인했습니다. 다른 버전에서는 설치된 패키지의 타입과 changelog도 확인하세요.

설정 위치와 버전 읽는 법

React 플러그인 0.9.0부터 targetSdkVersion이 deprecated되었고 engineVersion의 별칭으로 유지됩니다. 확인한 0.18.3·0.20.2는 둘 다 허용하지만, 새 설정에는 engineVersion을 사용하세요. 둘을 함께 지정하면 engineVersion이 우선하며, 둘 다 생략한 플러그인 기본값은 3.2입니다. 아래에서 target SDK라고 할 때는 엔진에 전달된 이 대상 버전을 뜻합니다. 패키지 변경 이력

두 플러그인에 모두 있는 키도 있지만, 모든 플래그를 pluginLynxConfig에 모을 수는 없습니다. 확인한 React 플러그인은 공유된 config 중 자신의 기본 옵션 목록에 있는 키만 읽어 덮어씁니다. config 플러그인은 공개 키를 검증한 뒤 컴파일러·페이지 설정으로 전달하며, 목록 밖의 키는 오류로 거부합니다. 같은 키는 한 곳에서만 설정하세요. React 구현 · Config 구현

SEED에서 중요한 플래그

활성화 유지는 기능이 필요하다는 뜻이고, 명시 설정 유지는 코드에 옵션을 남겨야 한다는 뜻입니다. 다음 표는 확인한 Engine 3.6·3.7·3.8·3.9·4.0·4.1 출시 tag의 설정을 기준으로 합니다. true/false는 별도 호스트 override가 없을 때의 값이며, 예외는 아래에 설명합니다.

Selector·Invalidation의 생략 조건은 React 플러그인 0.18.3·0.20.2에서 기본값 true를 확인했다는 것입니다. “Engine 3.6 이상에서 항상 켜진다”는 뜻이 아닙니다. 더 오래된 플러그인의 기본값 변경 최초 버전은 미확인입니다.

CSS 매칭과 갱신

enableCSSSelector와 enableCSSInvalidation의 엔진 컴파일러 설정 기본값은 모두 false입니다. React 플러그인이 둘 다 true를 넣으므로 최소 예제에 반복하지 않아도 됩니다. 명시할 필요가 있다면 다음 위치를 사용하세요. 엔진 설정 · React 옵션

둘 다 공통 CSS 컴파일러·스타일 엔진의 옵션이며, 설정 정의의 도입 기록은 Selector 2.8, Invalidation 2.10입니다. 이 도입 기록은 React 플러그인의 기본 활성화 시점을 뜻하지 않습니다.

pluginReactLynx({
  enableCSSSelector: true,
  enableCSSInvalidation: true,
});

Invalidation은 .a .b 같은 선택자가 있을 때 상위 요소의 class가 바뀌면 영향을 받는 하위 요소의 스타일을 다시 계산하도록 합니다. 끄면 전체 스타일을 재계산하는 것이 아니라, 결합 선택자가 처음에는 맞더라도 후속 변경에 따른 관련 스타일 갱신이 수행되지 않을 수 있습니다.

영향받는 요소를 모으고 갱신하는 데에도 비용이 있습니다. 공식 문서는 이런 선택자 사용이 없다면 성능을 위해 끌 수 있다고 설명하지만, SEED와 앱의 상태·테마 갱신에 필요한지 확인 없이 끄지 마세요. 공식 설명 · 3.6 문서 원본

이 플래그가 웹의 모든 선택자를 지원한다는 뜻은 아닙니다. SEED Lynx의 상태 스타일은 recipe variant가 만든 className을 사용합니다. 웹의 data-* attribute selector를 그대로 옮길 수 있다고 가정하지 마세요.

CSS 상속과 인라인 변수

두 옵션은 서로 다른 기능입니다. 공식 Config 설명 · 3.6 설정 정의

CSS 상속은 Lynx가 지원하는 속성 범위에 적용됩니다. 웹의 모든 속성이 동일하게 상속된다는 뜻은 아닙니다. 상속 목록을 바꿔야 한다면 pluginReactLynx의 customCSSInheritanceList를 사용하세요. 기본 목록에 추가하는 방식이 아니라 목록을 지정하는 옵션이므로 SEED가 사용하는 상속 속성을 빠뜨리지 않도록 확인하세요.

enableCSSInlineVariables를 끈다고 스타일시트의 CSS 변수 자체가 없어지는 것은 아닙니다. 또한 class를 바꾸는 테마 전환과 인라인 변수 갱신을 같은 기능으로 보지 마세요.

텍스트와 레이아웃

3.6 정의 · 3.8 정의 · 4.1 정의 · 4.1 decoder · fixed 처리

터치와 호스트 설정 갱신

enableMultiTouch와 globalPropsMode는 SEED를 사용하는 화면의 상호작용과 설정 갱신에 중요하지만, 모든 화면에서 특정 값을 강제하는 옵션은 아닙니다.

멀티터치 공식 설명 · 3.6 설정 정의 · globalPropsMode 공식 설명

확인한 React 0.125.0에서 useGlobalProps()는 "event" 모드의 변경 이벤트를 직접 구독합니다. 따라서 이 훅을 쓰는 SEED 컴포넌트에 별도 이벤트 리스너를 중복 추가할 필요는 없습니다. 반면 앱 코드가 lynx.__globalProps를 직접 읽기만 하면 변경을 구독하지 않으므로, 테마 등 런타임 변경에 반응해야 하는 곳에서는 훅이나 명시적인 이벤트 구독을 사용하세요. React 구현

enableMultiTouchParamsCompatible는 멀티터치 활성화와 별개의 payload 호환 옵션입니다. 공개 설정에서 빠진 이 옵션을 대신 넣지 말고, 필요한 기능에 맞춰 enableMultiTouch를 설정하세요.

기능을 사용할 때 선택하는 플래그

다음 옵션은 SEED 전체의 필수 설정이 아닙니다. 각 화면이 해당 API나 동작에 의존할 때 선택하세요. 표의 도입 기록은 엔진 설정 정의의 Since입니다. 플랫폼별 실제 지원이 불명확한 항목은 별도로 표시했습니다.

이벤트와 제스처

공식 Config 설명 · 3.6 정의와 fallback · 4.1 정의 · Config changelog

SEED PullToRefresh를 사용하는 앱은 다음 옵션을 기존 React 플러그인 설정에 합치세요. @lynx-js/gesture-runtime이 Content의 네이티브 스크롤과 당김 제스처를 중재할 때 Gesture Handler 경로를 사용합니다. Since 2.16은 엔진 설정의 도입 기록이며, SEED의 최소 지원 엔진 3.6을 낮춘다는 뜻은 아닙니다.

pluginReactLynx({
  engineVersion: "3.6",
  enableNewGesture: true,
});

PullToRefresh를 사용하지 않는 앱에는 이 플래그가 필요하지 않을 수 있으므로 위의 최소 권장 설정에는 넣지 않았습니다.

enableMultiTouch는 현재 Config에도 공개되어 있습니다. enableMultiTouchParamsCompatible가 사라졌다는 이유로 멀티터치 자체가 지원 종료되었다고 해석하지 마세요. 최신 공개 API에서 빠진 옵션을 계속 제어해야 하는 앱은 호스트의 설정 경로와 기존 동작을 확인해야 하며, 단순히 React 플러그인으로 옮기면 안 됩니다.

관찰과 렌더링

Observer 기본값 변경 · 3.9 decoder · 3.9 settings fallback · 4.1 decoder · 4.1 settings fallback

Observer는 빌드와 엔진을 함께 확인해야 합니다.

• React 빌드: 위에서 확인한 두 조합의 @lynx-js/template-webpack-plugin 0.15.0·0.16.1은 페이지 설정에 enableNewIntersectionObserver: true를 넣습니다. Config나 다른 플러그인으로 덮어쓰지 않았다면 명시 설정을 생략할 수 있습니다. 이 빌드 기본값의 최초 도입 버전은 미확인입니다. 출시 템플릿 코드
• 엔진: 설정 정의 기본값은 3.8.1까지 false, 3.9.0부터 true입니다. 하지만 3.9·4.1 decoder도 번들에 값이 없으면 settings를 읽으며, 그 fallback은 false입니다. 다른 빌드 경로를 쓰는 앱에서 Engine 3.9 이상이라는 이유만으로 삭제하면 안 됩니다.

성능·대체 스타일 경로

아래 항목은 모두 config 플러그인 0.2.0부터 기본 공개 설정에서 제외되었습니다. 최신 예제에 추가하지 마세요. 구형 config 플러그인 0.1.1에서는 허용되지만, SEED에 필요한 일반적인 최적화 설정으로 일괄 권장하지 않습니다. Config changelog · 현재 타입

3.6 정의 · 4.1 정의 · CSS class 병합 구현 · SimpleStyle 구현 · 텍스트 캐시 사용처

이전 설정 정리하기

먼저 빌드 패키지 버전을 확인하고, 그 다음 기존 앱의 동작 의존성을 확인하세요. @lynx-js/config-rsbuild-plugin은 0.1.1에서 type-config 3.6.0을 사용하다가, 0.2.0에서 4.1.1의 공개 목록으로 전환했습니다. 아래 제외된 키는 별도 deprecated 유예 없이 기본 타입·검증에서 빠졌습니다. 변경 이력

enableCSSStrictMode는 확인한 Engine 3.6·4.1에도 파서 설정과 사용처가 남아 있습니다. 예를 들어 length 파서는 이 값에 따라 잘못된 값의 진단을 출력하지만, 그 예만으로 false이면 모든 잘못된 길이를 허용한다거나 true이면 웹과 완전히 같은 파싱이 된다고 설명할 수 없습니다. 파서 구현

근거와 확인 범위

이 문서는 출시된 패키지의 타입·기본값·설정 전달 코드, 공식 버전 문서, Engine release tag를 비교한 결과입니다. 네이티브 기기에서 각 조합을 실행한 결과는 아닙니다.

• 도입 기록: 표의 Since는 3.6 설정 정의와 4.1 설정 정의의 기록입니다. 현재 API 문서에는 일부 과거 기능이 Since 3.2로 표기되어 있어, 도입 기록과 기본 활성화 시점을 혼동하지 않도록 이전 tag를 함께 참고했습니다. 3.2 이전 항목의 최초 출시 tag와 플랫폼별 도입 시점은 별도로 확정하지 못했습니다.
• 정확한 경계 미확인: enableTransformedTouchPosition의 3.6 도입 기록과 3.6.0 tag 사이의 차이, Selector·Invalidation이 React 기본 true가 된 최초 패키지 버전, Observer의 템플릿 기본 활성화 최초 버전, VSync flush의 플랫폼별 효과·변경 경계는 미확인입니다.
• 삭제 판단: 공개 설정 제외를 엔진 기능 제거로 표시하지 않았습니다. 호스트 fallback이나 다른 실행 경로가 있는 플래그는 엔진 버전만으로 “설정 불필요”라고 단정하지 않습니다. 확인하지 않은 이후 버전과 next/main의 미출시 변경도 적용하지 않습니다.