003 - 동적 구성
플러그인은 구성 우선(config-first) 방식인 프론트엔드 시스템용으로 생성되었어요. 즉 코드를 변경하지 않고도 app-config.yaml을 통해 프론트엔드 컴포넌트를 제어할 수 있어요. 이 글에서는 확장을 비활성화하고, 확장을 구성하고, 사용자 정의 구성 스키마를 추가하는 방법을 설명드릴게요.
출처: 문서
본문
플러그인은 구성 우선 방식인 프론트엔드 시스템용으로 생성되었어요. 즉 코드를 변경하지 않고도 app-config.yaml을 통해 프론트엔드 컴포넌트를 제어할 수 있어요.
확장 비활성화하기
프론트엔드 시스템의 모든 확장은 구성을 통해 켜거나 끌 수 있어요. todo 페이지를 완전히 비활성화하려면 app-config.yaml에 다음을 추가해요:
app-config.yaml
app: extensions: - 'page:todo': false
앱을 시작하고 /todo로 이동해 보세요 — "page not found" 응답을 받을 거예요. 줄을 제거하거나 true로 설정하면 다시 살아나요.
확장 구성하기
모든 확장 블루프린트는 채택자가 app-config.yaml을 통해 설정할 수 있는 자체 구성 옵션 집합을 지원해요. PageBlueprint는 기본적으로 path와 title을 지원해요. 페이지 제목을 바꾸려면 다음을 추가해요:
app-config.yaml
app: extensions: - page:todo: config: title: My Custom Todo List
앱을 재시작하면 페이지 제목으로 "My Custom Todo List"가 보일 거예요. 코드 변경은 필요 없어요 — PageBlueprint가 title 구성을 읽어서 페이지 헤더에 자동으로 전달해요.
사용자 정의 구성 추가하기
내장 구성 옵션만으로 부족할 때 자체 구성 스키마를 정의할 수 있어요. 값은 자동으로 검증되고 확장 팩토리로 전달되므로, 컴포넌트가 원시 구성을 직접 읽을 필요가 없어요.
예를 들어 구성 가능한 부제(subtitle)를 추가해 볼게요. plugin.tsx에서 PageBlueprint.make에서 PageBlueprint.makeWithOverrides로 전환하고 구성 스키마를 선언해요:
import { z } from 'zod';export const page = PageBlueprint.makeWithOverrides({ configSchema: { subtitle: z.string().optional(), }, factory(origFactory, { config }) { return origFactory({ path: '/todo', routeRef: rootRouteRef, loader: () => import('./components/TodoPage').then(m => ( <m.TodoPage subtitle={config.subtitle} /> )), }); },});
그런 다음 TodoPage를 업데이트해서 새 prop을 받고 렌더링하게 해요:
export function TodoPage({ subtitle }: { subtitle?: string }) { // ... existing component code return ( <Container> {subtitle && <Typography variant="subtitle1">{subtitle}</Typography>} {/* rest of the page */} </Container> );}
채택자는 이제 app-config.yaml에서 부제를 설정할 수 있어요:
app-config.yaml
app: extensions: - page:todo: config: subtitle: Things to get done today
값은 구성을 거쳐 스키마 검증을 통과하고 팩토리 함수로 들어간 다음, 마침내 컴포넌트에 prop으로 전달돼요 — configApiRef가 필요 없어요.
왜 동작하나요?
프론트엔드 시스템은 구성을 일급 개념으로 취급해요. 각 확장은 고유 ID(예: page:todo)로 앱에 등록돼요. 앱은 구성의 app.extensions 섹션을 읽어 어떤 확장을 활성화·비활성화·구성할지 결정해요.
확장 블루프린트는 Standard Schema와 JSON Schema를 지원하는 검증기를 사용해서 configSchema를 선언해요. 이 예시에서 스키마를 소유한 플러그인 패키지는 Zod v4를 import해요. 앱이 시작될 때 프레임워크는 구성을 스키마에 대해 파싱하고 검증한 다음, 결과를 확장의 팩토리 함수에 전달해요. 즉 컴포넌트가 런타임에 원시 구성 문자열을 읽는 대신 타입이 지정되고 검증된 값을 받는 거예요.
이 구성 우선 접근법은 플러그인의 채택자가 코드를 포크하지 않고도 동작을 커스터마이징할 수 있다는 것을 의미해요 — 구성 파일만 조정하면 돼요.