ADR015: 요소 및 컴포넌트 옵션을 위한 타입과 명명

원문 보기 위키 갱신 2026.10.07

지금까지 JSX 요소나 컴포넌트를 제공하기 위한 옵션을 정의하는 방법에 대한 명확한 표준이 없었습니다. 이로 인해 공개 API에 서로 다른 패턴이 혼재하게 되었으며, 이 ADR은 이를 표준화하고자 합니다.

출처: 문서

본문

맥락

결정

JSX 요소나 컴포넌트를 제공하기 위한 옵션을 정의할 때는 다음 옵션 프로퍼티 이름과 타입 중 하나를 사용할 것입니다.

단순 요소(Simple element)

이 옵션은 단순한 동기식 JSX 요소가 제공될 때 사용합니다. lazy-loading이 필요하지 않은 영역에서만 사용해야 합니다.

{  element: JSX.Element;}

단순 컴포넌트(Simple component)

이 옵션은 단순한 동기식 컴포넌트가 제공될 때 사용합니다. lazy-loading이 필요하지 않은 영역에서만 사용해야 합니다.

{  component: (props: { ... }) => JSX.Element | null}

비동기 요소 로더(Async element loader)

이 옵션은 단순한 비동기 JSX 요소가 제공될 때 사용합니다. 단일 인스턴스만 만들고 컴포넌트에 프로퍼티를 전달할 필요가 없을 때 선호되는 옵션입니다. 이 형식은 로더 구현에서 추가 프로퍼티를 전달하기 위한 클로저 생성을 단순화합니다.

{  loader: () => Promise<JSX.Element>;}

비동기 컴포넌트 로더(Async component loader)

이 옵션은 단순한 비동기 컴포넌트가 제공될 때 사용합니다. 컴포넌트에 프로퍼티를 전달해야 하거나 여러 인스턴스가 필요하고 lazy-loading이 요구될 때 선호되는 옵션입니다.

{  loader: () => Promise<(props: { ... }) => JSX.Element | null>}

임의 컴포넌트 로더(Any component loader)

이 옵션은 비동기 컴포넌트 로더와 같은 경우에 사용하지만, 동기식 로딩의 옵션도 필요할 때 사용합니다. 동기식의 경우에도 항상 외부 로더 함수를 갖는 구조는 런타임에서 로더의 타입을 결정할 수 있게 해줍니다.

{  loader: (() => props => JSX.Element | null) | (() => Promise<props => JSX.Element | null>)}

이 로더를 소비할 때는 무조건 React.lazy로 감싸야 한다는 점에 유의하세요. React.lazy 호출은 렌더 함수 내에서 호출할 수 없기 때문에 렌더링까지 미룰 수 없기 때문입니다. 즉, 먼저 로더를 호출해 반환 값이 프로미스인지 확인할 수 없으므로, 대신 무조건 React.lazy로 감싸야 합니다. 따라서 이 로더 중 하나를 옵션으로 받아들이는 구현은 대략 다음과 같아야 합니다.

const LazyComponent = React.lazy(() =>  Promise.resolve(options.loader()).then(loaded => ({ default: loaded })),);

결과

@backstage/frontend-* 패키지의 새 프론트엔드 시스템을 위한 모든 API를 갱신할 것입니다.

@backstage/core-* 패키지의 기존 프론트엔드 시스템을 위한 기존 API는 갱신하지 않을 것입니다.