# [[Public APIs|Public APIs]]

## 📌 Brief Summary
프론트엔드 아키텍처 및 컴포넌트 라이브러리 설계에서 퍼블릭 API(Public APIs)는 컴포넌트나 패키지가 외부와 상호작용하기 위해 노출하는 명시적인 계약이자 안정적인 진입점(entry point)을 의미합니다 [1, 2]. 이는 컴포넌트가 받는 속성(props)과 반환하는 이벤트(callbacks)를 정의하며, 내부 구현 세부 사항을 캡슐화합니다 [2]. 명확한 퍼블릭 API를 강제하는 것은 패키지 간의 무분별한 참조를 방지하고, 변화하는 요구사항 속에서도 안전하게 확장 가능한 UI를 구축하는 데 필수적입니다 [3, 4].

## 📖 Core Content
*   **컴포넌트 API 설계의 중요성:** 재사용 가능한 UI를 구축하는 것은 단순히 코드를 적게 작성하는 것이 아니라, 지속적인 변화에서 살아남을 수 있는 API를 설계하는 것입니다 [3]. 좋은 컴포넌트 API는 직관적이고 오용하기 어려워야 하며, 최소한의 속성(props)만 노출해야 합니다 [5]. 이는 컴포넌트가 무엇을 받아들이고, 무엇을 반환하며, 절대 하지 말아야 할 행동(예: 부모 상태 변이)을 규정하는 명시적 계약(Explicit Contracts) 역할을 수행합니다 [2].
*   **모노레포와 패키지 경계 관리:** 대규모 모노레포 환경에서는 모듈성 유지를 위해 엄격한 퍼블릭 API 노출이 필요합니다 [1, 4]. 소비자는 내부의 깊은 경로(예: `import Button from "@acme/ui/src/button/Button"`)가 아닌, 의도적으로 노출된 안정적인 진입점(예: `import { Button } from "@acme/ui"`)을 통해서만 모듈을 가져와야 합니다 [4]. 이를 강제하기 위해 패키지의 `package.json`에서 `exports` 필드를 정의하거나 [[ESLint|ESLint]] 규칙을 적용하여 딥 임포트(deep imports)를 차단해야 합니다 [4, 6].
*   **FSD([[Feature-Sliced Design|Feature-Sliced Design]])와의 통합:** 확장 가능한 프론트엔드 아키텍처 방법론인 FSD는 슬라이스(slice) 경계에서 명시적인 퍼블릭 API 사용을 권장합니다 [7]. 애플리케이션은 공유 패키지나 슬라이스의 `index.ts` 같은 퍼블릭 API 파일을 통해서만 임포트하고, 내부 파일은 철저히 내부에 유지되도록 설계함으로써 의도치 않은 결합(accidental coupling)을 크게 줄일 수 있습니다 [7, 8].
*   **거버넌스 및 브레이킹 체인지 방지:** 여러 앱에서 사용되는 공유 패키지(예: `packages/ui`)의 퍼블릭 API가 변경될 경우 파급 효과가 크므로, 예측 불가능한 시스템 중단을 막기 위해 엄격한 관리가 필요합니다 [9, 10]. `CODEOWNERS` 등을 이용해 소유권을 명확히 하고, 공유 모듈의 퍼블릭 API에 변경 사항이 있을 때는 반드시 코드 리뷰를 요구하는 정책을 수립해야 합니다 [9, 10].

## 🔗 Knowledge Connections
- **Related Topics:** [[Component API Design|Component API Design]], Monorepo Architecture, [[Feature-Sliced Design (FSD)|Feature-Sliced Design (FSD]], Explicit Contracts
- **Projects/Contexts:** 대규모 리액트 애플리케이션의 모노레포 구축(Nx/[[Turborepo|Turborepo]]), 확장 가능하고 유지보수 용이한 재사용 UI 컴포넌트 라이브러리 설계
- **Contradictions/Notes:** 컴포넌트 내부의 복잡성은 숨기고 외부로는 단순하고 일관된 진입점을 제공해야 한다는 원칙은, 단일 컴포넌트 설계와 대규모 패키지 구조 설계 양쪽 모두에 공통적으로 핵심적인 지침으로 강조됩니다 [2, 4].

---
*Last updated: 2026-04-26*