Lynx

Installation

Lynx 프로젝트에서 SEED를 설치하고 사용하는 방법을 알아봅니다.

의존성 설치

필요한 공통 의존성을 설치해요. 스타일링 라이브러리는 다음 단계에서 선택해요.

npm install @seed-design/lynx-react @seed-design/lynx-css

스타일링 라이브러리 선택하기

Vanilla Extract 또는 Tailwind CSS v4 중 프로젝트에 맞는 방식을 선택하세요. 정적 CSS를 권장하는 이유와 레이아웃 작성 예제는 Styling 가이드에서 확인하세요.

스타일링 방식작성 방법설정 가이드
Vanilla Extract.css.ts에서 타입이 있는 스타일과 SEED 토큰을 작성해요.Vanilla Extract
Tailwind CSS v4className에 utility class를 조합해요.Tailwind CSS 4

선택한 가이드에서 의존성, 빌드 설정, SEED base.css와 앱 entry의 CSS import까지 적용한 뒤 다음 단계로 진행하세요. 각 가이드의 Rspeedy·Rsbuild 요구사항을 먼저 확인하세요. Vanilla Extract 플러그인 0.2.0은 Rsbuild 1을 요구하며, Tailwind v4 가이드는 Rsbuild 2 기반 구성을 다뤄요. 기존 Tailwind v3 프로젝트는 Tailwind CSS 3 설정을 유지할 수 있어요.

seed-design.json 생성하기

init 명령어 입력하기

npx @seed-design/cli init

seed-design 설정

@lynx-js/react가 설치되어 있으면 프레임워크가 자동으로 Lynx로 감지돼요.

◇  TypeScript를 사용중이신가요?
│  Yes
│
◇  어떤 프레임워크를 사용하시나요?
│  Lynx
│
◇  seed-design 폴더 경로를 입력해주세요. (기본값은 프로젝트 루트에 생성됩니다.)
│  ./seed-design
│
◇  개선을 위해 익명 사용 데이터를 수집할까요?
│  Yes

seed-design path alias 설정하기

위에서 설정한 seed-design.json path의 경로와 동일해야 해요.

TypeScript가 snippet import를 해석할 수 있도록 루트 tsconfig.json에 path alias를 추가해요.

tsconfig.json
{
  "compilerOptions": {
    // ... your options
    "baseUrl": ".",
    "paths": {
      "seed-design/*": [
        "./seed-design/*"
      ]
    }
  }
}

Lynx 템플릿처럼 src/tsconfig.json이 별도로 있고 composite 프로젝트를 사용하는 경우, 생성된 snippet 경로도 include에 추가해야 해요.

src/tsconfig.json
{
  "include": [
    "./**/*.ts",
    "./**/*.tsx",
    "../seed-design/**/*.ts",
    "../seed-design/**/*.tsx"
  ]
}

Rspeedy/Rspack도 같은 alias를 알아야 런타임 빌드에서 seed-design/* import를 해석할 수 있어요.

lynx.config.ts
import { defineConfig } from "@lynx-js/rspeedy";
import { fileURLToPath } from "node:url";

const seedDesignDir = fileURLToPath(new URL("./seed-design", import.meta.url));

export default defineConfig({
  resolve: {
    alias: {
      "seed-design": seedDesignDir,
    },
  },
});

@karrotmarket/lynx-*-icon 아이콘 패키지를 사용하는 경우 SVG asset을 Lynx에서 표시할 수 있도록 @seed-design/rsbuild-plugin-lynx-icon도 설정해야 해요. 자세한 설정은 Iconography에서 확인하세요.

Lynx 피쳐 플래그 설정하기

SEED의 CSS 상속, 인라인 변수, Dynamic/Static 타이포그래피, fixed 요소를 위한 기본 설정이에요. CSS Selector와 Invalidation은 pluginReactLynx의 기본값을 사용하므로 반복해서 설정하지 않아도 돼요. 아래 예제는 React 플러그인 0.18.3·0.20.2, config 플러그인 0.2.2·0.2.3에서 허용되는 옵션을 사용해요.

npm install @lynx-js/config-rsbuild-plugin
lynx.config.ts
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",
    }),
    // ... 기존 플러그인들
    pluginLynxConfig({
      enableCSSInheritance: true,
      enableCSSInlineVariables: true,
      fontScaleEffectiveOnlyOnSp: true,
      enableFixedNew: true,
    }),
  ],
});

기존 pluginReactLynx 호출에 옵션을 합쳐 사용하고, 같은 플러그인을 중복 등록하지 마세요. engineVersion은 앱의 최소 대상 버전이에요. 기존 앱이 더 높은 버전을 요구한다면 그 값을 유지하세요. enableTextRefactor는 이 대상 버전에서 기본 활성화되며, enableCSSStrictMode: false를 SEED의 필수 설정으로 추가할 필요는 없어요.

PullToRefresh를 사용하는 앱은 기존 pluginReactLynx 설정에 enableNewGesture: true를 추가하세요. PullToRefresh는 @lynx-js/gesture-runtime의 NativeGesture로 Content 스크롤과 당김 제스처를 중재해요.

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

이 플래그는 PullToRefresh를 쓰는 앱에 필요한 조건부 설정이에요. 도입 기록과 버전별 설정 조건은 Feature Flags의 이벤트와 제스처를 확인하세요.

엔진·빌드 도구 버전별로 유지하거나 생략할 설정과 선택 옵션은 Feature Flags에서 확인하세요.

컴포넌트를 한번 사용해볼까요?

npx @seed-design/cli add ui:switch

(선택) lynx-console 설치하기

lynx-console은 Lynx 앱 안에서 콘솔 로그, 네트워크, 성능 지표를 확인할 수 있는 개발자 도구예요.

npm install lynx-console

앱 entry에서 초기화하고 컴포넌트를 추가해주세요.

src/App.tsx
import {
  initLogMonitor,
  initMainThreadConsole,
  initNetworkMonitor,
  initPerformanceMonitor,
} from "lynx-console/setup";
import LynxConsole from "lynx-console";

initLogMonitor();
initMainThreadConsole();
initNetworkMonitor();
initPerformanceMonitor();

function App() {
  return (
    <view>
      {/* your app */}
      <LynxConsole />
    </view>
  );
}

자세한 사용법은 lynx-console GitHub을 참고하세요.

Last updated on

이전 문서Overview다음 문서Styling

목차

의존성 설치스타일링 라이브러리 선택하기seed-design.json 생성하기init 명령어 입력하기seed-design 설정seed-design path alias 설정하기Lynx 피쳐 플래그 설정하기컴포넌트를 한번 사용해볼까요?(선택) lynx-console 설치하기