[TypeScript] zero-install 환경에서의 cannot be used as a JSX component. 해결방안 트러블 슈팅

문제 상황

팀 프로젝트를 모노레포로 관리하다가 발생한 오류인데, 모노레포를 사용하다 보면 한 번쯤 겪게 되는 타입 오류이다.

'Wrapper' cannot be used as a JSX component. Its type 'StyledComponent ... 

처음엔 타입과 관련된 오류라는 것은 확실하다고 생각했고, 다음과 같은 문제들을 예상했다. (이때까지만 해도 금방 해결될 줄 알았다.)

1. 워크스페이스마다 다른 TypeScript 버전 사용
2. 워크스페이스마다 다른 Emotion 버전 사용
3. tsconfig.json 작성 실수

이 정도 문제일 것으로 예상하여 해결 방법을 정리해 보았다.

• 문제 1 → 모든 워크스페이스의 TypeScript 버전 통합
• 문제 2 → 모든 워크스페이스의 Emotion 버전 통합
• 문제 3 → tsconfig.json 검토 후 수정

바로 해결 방안들을 실행해 보았지만, 놀랍게도 오류는 그대로였다.

원인 분석

오류는 생각보다 쉽게 해결되지 않았고, 원인을 다시 분석해 보기로 했다.

cannot be used as a JSX component.

이 오류가 무엇을 의미하는지 검색해 보니, 나와 같은 문제를 겪고 해결한 분의 블로그를 발견했다.

관련 블로그

이 블로그에는 다음과 같은 내용이 적혀 있었다.

올바르지 않은 패키지 설치로 인해 React 17버전과 18버전의 타입 정의 파일(d.ts) 두 개가 충돌해서 발생한 오류였다. React 앱에는 해당 버전에 맞는 d.ts 파일이 하나만 존재해야 한다.

이를 확인하기 위해 워크스페이스들의 @types/react 버전과 ./yarn/cache의 @types/react 버전을 비교해 보았다.

.
├── packages/
│   ├── package-a/        # 첫 번째 패키지
│   │   ├── src/          # 소스 코드
│   │   │   ├── index.ts
│   │   │   └── ...
│   │   ├── package.json  # @types/react: "18.3.18"
│   │   └── ...
│   ├── package-b/        # 두 번째 패키지
│   │   ├── src/          # 소스 코드
│   │   │   ├── index.ts
│   │   │   └── ...
│   │   ├── package.json  # @types/react: "19.0.8" <<<<<< 문제가 발생한 패키지
│   │   └── ...     
│   ├── package-c/        # 세 번째 패키지
│   │   ├── src/          # 소스 코드
│   │   │   ├── index.ts
│   │   │   └── ...
│   │   ├── package.json  # @types/react: "18.3.18"
│   │   └── ...
│   └── ...

문제의 원인은 워크스페이스 간 @types/react 버전 차이로 인해 발생한 것이었고, 문제의 패키지(package-b)의 @types/react 버전을 18.3.18로 맞추니 오류가 해결되었다.

느낀 점

이처럼 패키지 버전을 일관되게 유지해야 하는 프로젝트에서는, 라이브러리가 버전업될 때마다 관리가 골치 아파질 수 있음을 깨달았다.

이러한 상황을 방지하기 위해 워크스페이스의 버전을 자동으로 통합하는 방법이 있는지 찾아보았고, Peer Dependency를 활용하면 자식 워크스페이스의 버전이 상위 워크스페이스의 버전을 자동으로 따르도록 설정할 수 있다는 사실을 알게 되었다.

앞으로는 패키지를 무분별하게 설치하지 않고, 반드시 버전 통합을 고려한 후 설치해야겠다고 다짐했다.

참고:
Peer Dependency 참고

에러 디버깅 참고