ADR004: 모듈 내보내기 구조
@backstage/core-components 같은 패키지의 내보내기 수가 늘어나면서, 여러 질문에 답하기가 점점 어려워지고 있습니다.
출처: 문서
본문
맥락
@backstage/core-components 같은 패키지의 내보내기 수가 늘어나면서, 다음과 같은 질문에 답하기가 점점 더 어려워지고 있습니다.
이 모듈의 내보내기가 패키지에서도 내보내지나요?
또는
이 디렉토리에서 무엇이 내보내지나요?
현재 우리는 내보내기 구조를 어떻게 구성할지에 대한 패턴을 사용하지 않습니다. 디렉토리 트리의 깊은 곳까지 가는 패키지 수준의 re-export, 각 디렉토리의 얕은 re-export, *를 사용한 내보내기와 각 기호의 명시적 목록 등이 혼재되어 있습니다. 이런 혼재와 예측 가능성의 부족은 모듈의 경계를 추론하기 어렵게 만들며, 예를 들어 주어진 파일에서 기호를 내보내도 안전한지 알기 어렵게 합니다.
결정
우리는 각 내보낸 기호를 index 파일들을 통해 패키지의 루트인 src/index.ts까지 추적 가능하게 만들 것입니다. 각 index 파일은 자신의 바로 아래 디렉토리 자식들에서만 re-export하며, re-export를 갖는 것은 index 파일뿐입니다. 이렇게 하면 다음과 같은 파일 트리가 됩니다.
index.tscomponents/index.ts /ComponentX/index.ts /ComponentX.tsx /SubComponentY.tsxlib/index.ts /UtilityX/index.ts /UtilityX.ts /helper.ts
예를 들어 SubComponentY가 패키지에서 내보내지는지 확인하려면, 인접한 index 파일에서 시작해 루트 방향으로 index 파일들을 거슬러 올라가면 됩니다. 어떤 index 파일이 이전 것을 내보내지 않는다면, 그 기호는 공개적으로 내보내지지 않습니다. 예를 들어 components/ComponentX/index.ts가 SubComponentY를 내보내지만 components/index.ts가 ./ComponentX를 re-export하지 않는다면, SubComponentY가 패키지 외부로 내보내지지 않는다는 것을 확신할 수 있습니다. 이 규칙은 예를 들어 루트 index.ts가 ./components/ComponentX를 re-export한다면 깨질 것입니다.
또한, 다른 index 파일을 re-export하는 index 파일은 항상 와일드카드 형식을 사용해야 합니다. 즉:
// in components/index.tsexport * from './ComponentX';
index가 아닌 파일에서 기호를 re-export하는 index 파일은 항상 모든 내보내기를 나열해야 합니다. 즉:
// in components/ComponentX/index.tsexport { ComponentX } from './ComponentX';export type { ComponentXProps } from './ComponentX';
내부 크로스 디렉토리 import는 index가 아닌 모듈에서 index 모듈로 허용됩니다. 예:
// in components/ComponentX/ComponentX.tsximport { UtilityX } from '../../lib/UtilityX';
index 파일을 우회하는 import는 권장되지 않지만, 때로는 필요할 수도 있습니다. 예:
// in components/ComponentX/ComponentX.tsximport { helperFunc } from '../../lib/UtilityX/helper';
결과
우리는 코드베이스의 내보내기 구조를 재구성하기 위해 적극적으로 노력할 것입니다. @backstage/core-components와 @backstage/backend-common 같은 라이브러리 패키지를 우선시할 것입니다.
가능하다면 lint 규칙 같은 도구를 추가해 내보내기 구조를 강제하는 데 도움을 주겠습니다.