# Composio Core (composio-core)
Composio Core는 선언형 구성(declaration-based composition)을 중심으로 작동하는 모듈식 라이브러리 프레임워크이다. 데이터와 UI의 구성 단위를 결합하고, 재구성(Recomposition)과 확장성(Extensibility)을 핵심 목표로 설계되었다. 플랫폼에 의존하지 않는 Renderer 추상화와 플러그인 시스템을 통해 다양한 환경(Web, Native, 서버 사이드 렌더링)에서 일관된 구성 패턴을 제공한다.
---
## 개요
- 목적: 복잡한 UI/데이터 흐름의 구성 요소를 재사용 가능하고 예측 가능한 방식으로 조합하도록 지원
- 접근 방식: 선언형 DSL(도메인 특화 언어)과 런타임 렌더러를 분리하여, 구성 로직과 렌더링 엔진 간의 결합도를 낮춤
- 대상: 프런트엔드 개발자, UI/UX 시스템 엔지니어, 모듈식 아키텍처를 추구하는 프로젝트
---
## 특징
- 선언형 구성(Declarative Composition): 구성의 목표 상태를 기술하면 렌더러가 차이를 계산하여 업데이트를 반영
- 모듈식 확장성(Modularity): 플러그인 API를 통해 새로운 렌더링 대상, 새로운 노드 타입, 새 로직을 손쉽게 추가
- 플랫폼 독립성(Platform Agnosticism): Renderer 추상화를 통해 Web, Native, CLI 등 다양한 타깃에 재적용 가능
- 재사용성과 조합성(Reusability and Composability): Component, Node, Fragment 단위의 재사용으로 대규모 시스템 관리 용이
- 성능 중심의 차이 계산(Reconciliation): 차이 패치(patch) 생성과 최소 업데이트로 렌더링 효율 최적화
- 관찰 가능성(Observability): 상태 변화, 이벤트, 렌더 파이프라인에 대한 로깅/트레이스 지원
---
## 아키텍처 개요
- Core: 구성의 데이터 모델과 생애 주기 관리
- Builder/DSL: 선언적 구성 정의를 위한 도구와 API
- Renderer: 목표 환경에 맞춘 렌더링 엔진 추상화
- Reconciler: 이전 상태와 새로운 상태 간의 차이를 계산하여 Patch를 생성
- Serializer/Deserializer: 구성 상태의 직렬화 및 복원
- Plugin System: 확장을 위한 플러그인 인터페이스
- Context & State: 컨텍스트 전달, 상태 관리 API
- Event & Instrumentation: 이벤트 핸들링 및 관측 도구
---
## 핵심 개념
- Composition(구성): 여러 Component와 Node를 조합하여 하나의 목표 상태를 만들기 위한 구조
- Component(컴포넌트): 재사용 가능한 UI/데이터 단위
- Node(노드): 구성 트리의 기본 단위로, 타입(type), props, children를 가진 객체
- Fragment(프래그먼트): 여러 노드를 그룹화하는 컨테이너
- Context(컨텍스트): 트리 전반에 걸쳐 값을 전달하는 저장소
- Hook(후크): 상태 관리나 생애 주기 로직을 재사용하는 패턴
- Patch(패치): 상태 차이를 표현하는 작은 변경 단위
- Renderer(렌더러): 실제 화면(또는 출력)으로 연결하는 모듈
- Plugin(플러그인): 기능 확장을 위한 독립 모듈
---
## 데이터 모델
- Node
- id: 고유 식별자
- type: 노드의 종류(예: Button, Text, Container)
- props: 속성 객체
- children: Node 배열
- Fragment
- nodes: Node 배열의 컨테이너
- Context
- map<String, any> 형태의 컨텍스트 저장소
- Patch
- ops: 차이 연산 배열(예: insert, update, delete)
- ComponentDefinition
- name: 문자열 식별자
- render: 렌더링 로직(또는 DSL 빌더)
- propsSpec: props의 타입/유효성 정의
---
## 사용 방법
- 설치 예시
- npm:
- npm install composio-core
- 또는 yarn:
- yarn add composio-core
- 기본 워크플로우 예제
- 간단한 구성 정의 및 렌더링 흐름
코드 예시 (TypeScript-ish, 가상 API 활용)
```ts
import { defineComponent, createComposer, render } from 'composio-core';
// 간단한 Button 컴포넌트 정의
const Button = defineComponent({
name: 'Button',
props: { label: 'string' },
render: (ctx) => ({
type: 'button',
props: { onclick: ctx.onClick },
children: [{ type: 'text', value: ctx.props.label }],
}),
});
// App 구성 정의
const App = defineComponent({
name: 'App',
render: (ctx) => {
return createComposer()
.add(Button, { label: 'Hello' })
.add(Button, { label: 'World' })
.build();
},
});
// 렌더 대상에 마운트
const root = document.getElementById('root');
render(App, root);
```
- 주의: 위 예제의 API는 컨텍스트에 따라 변경될 수 있으며, 실제 사용 시 공식 문서를 참조하십시오. 이 문서는 개념적 예시를 위한 가이드입니다.
- 간단한 To-do 구성 예시
```ts
const TodoItem = defineComponent({
name: 'TodoItem',
render: (ctx) => ({
type: 'li',
children: [{ type: 'text', value: ctx.props.text }],
}),
});
const TodoApp = defineComponent({
name: 'TodoApp',
render: (ctx) => {
const todos = ctx.props.todos;
return {
type: 'ul',
children: todos.map((t) => ({ type: TodoItem, props: { text: t } })),
};
},
});
```
---
## API 레퍼런스(주요 API)
- defineComponent(options): Component 정의
- options.name: 문자열
- options.props: Props 스키마
- options.render: 렌더링 로직(또는 DSL 빌더)
- createComposer(config?): Composer 빌더 생성
- add(component, props?): 노드 추가
- set(context, value): 컨텍스트 값 설정
- build(): 실행 가능한 구성 객체 생성
- render(component, target): 렌더러를 통해 목표(target)에 마운트
- patch(prevState, nextState): 상태 차이 계산 및 반영
- serialize(state): 구성 상태를 직렬화
- deserialize(serialized): 직렬화된 상태를 복원
- useState(initial): 지역 상태 훅(선택적)
- useContext(key): 컨텍스트 접근 훅(선택적)
- on(eventName, handler): 이벤트 구독
- emit(eventName, payload): 이벤트 방출
주의: 위 API 표기는 통합된 개념을 위한 참고용 예시이며, 실제 composio-core의 API 문서는 버전에 따라 다를 수 있습니다. 공식 레퍼런스를 확인하는 것을 권장합니다.
---
## 확장성 및 성능
- 플러그인 시스템
- 렌더링 목표 확장: DOM, Canvas, Native UI 등 다양한 타깃에 대응 가능
- 커스텀 노드 타입 추가: 새 구성 요소를 도메인에 맞게 확장 가능
- 성능 최적화
- 차이 기반 렌더링: 변경된 부분만 재렌더링
- 메모이제이션: 자주 재계산되는 값에 대한 캐시 제공
- 효과적인 컨텍스트 전달: 필요 시 컨텍스트 계층 최소화
---
## 개발 및 기여
- 테스트 전략: 단위 테스트, 통합 테스트, 렌더링 엔진 간 상호작용 테스트
- 코드 품질: 정적 타입 검사(TypeScript), 린트/포맷 도구 구성
- 기여 방법: 이슈 트래킹, 브랜치 전략, PR 가이드라인
- 로드맷: 로깅, 트레이싱, 성능 프로파일링 도구의 기본 지원
---
## 라이선스
- MIT License를 기본으로 채택하되, 프로젝트 정책에 따라 변경될 수 있음. 실제 배포 전 라이선스 파일을 확인하시기 바란다.
---
## 예제 및 의의
- 대규모 UI 시스템에서 구성 요소의 재사용성과 예측 가능성을 높이고, 렌더링 엔진과 비즈니스 로직을 분리함으로써 유지보수성을 개선한다.
- 플랫폼 간 코드 재사용성이 높아져 프로젝트 간 협업 효율이 증가한다.
---
관련 문서: [[Composio Core API Reference]], [[Composable Design Patterns for Composio]]