MUI SxProps 사용 시 무한 빌드 문제

MUI를 사용하는 Next.js 프로젝트에서 TypeScript 빌드가 끝나지 않는 현상이 발생했다. tsconfig.json 의 include 를 변경해가면서 범위를 좁혀나간 결과, SxProps 를 사용하는 부분이 원인이었다.

문제 상황

next build 를 실행하면 타입 유효성 검사 단계에서 빌드가 멈춰버린다. VSCode의 TypeScript 서버도 응답 불가 상태가 되어 강제 종료해야 했다.

import { SxProps } from "@mui/material";

이렇게 SxProps 를 임포트하는 것만으로도 문제가 발생한다.

원인

MUI GitHub 이슈를 확인해보니 원인이 나와 있었다.

https://github.com/mui/material-ui/issues/36043

SxProps 가 @mui/system/styleFunctionSx 에서 순환 임포트(circular import) 를 생성하는 것이 문제다. 특히 SystemStyleObject 타입 참조가 순환 참조를 일으키면서 TypeScript 컴파일러가 타입 해석을 무한히 시도하게 된다.

Next.js 13의 app 디렉토리와 TypeScript 조합에서 주로 발생하는 것으로 보인다.

임시 해결책

SxProps 를 직접 임포트하지 않고, SystemStyleObject 를 any 로 대체한 커스텀 타입을 정의해서 사용할 수 있다.

type SxProps<Theme extends object = {}> =
  | any  // SystemStyleObject<Theme> 대신
  | ((theme: Theme) => any)
  | ReadonlyArray<boolean | any | ((theme: Theme) => any)>;

타입 안정성은 떨어지지만 빌드가 멈추는 것보다는 낫다.

TypeScript 설정 확인하기

현재 TypeScript 설정이 어떻게 되어 있는지 확인하려면 아래 명령어를 사용하면 된다.

tsc --showConfig

tsconfig.json 의 상속과 확장이 모두 적용된 최종 설정을 확인할 수 있다.

디버깅 팁

비슷한 문제가 발생하면 tsconfig.json 의 include 에서 특정 디렉토리만 포함시켜 부분 빌드를 해본다.

{
  "include": ["src/components/specific-folder/**/*"]
}

빌드가 정상적으로 끝나는 범위를 찾으면, 거기서부터 범위를 넓혀가며 문제가 되는 파일을 특정할 수 있다.