next.js에서 local packages 사용시 Module parse failed 발생하는 이슈

문제

모노레포 환경에서 동작하는 next.js app(until) 에서 local 패키지(until-ui)를 사용하려 할 때 Module parse failed가 발생하였음..

원인

이 오류의 원인을 파악하기 위해서는 Next.js 의 동작에 대해서 이해할 필요가 있습니다.

1. Next.js의 기본 동작

Next.js는 node_modules 내의 패키지를 기본적으로 트랜스파일하지 않습니다. 이는 성능을 최적화하기 위한 설계로, 대다수의 npm 패키지가 이미 ES5 또는 CommonJS 형식으로 컴파일되어 있기 때문에 추가적인 트랜스파일이 필요하지 않다고 간주됩니다.

2. 로컬 패키지 또는 외부 패키지의 현대적 코드

만약 로컬 패키지 또는 외부 패키지가 ES6 이상의 최신 JavaScript 문법(예: ESModules, 최신 JSX 문법 등)을 포함하고 있다면, 이를 Next.js가 트랜스파일하지 않으면 실행 중에 브라우저에서 구문 오류(Syntax Error)가 발생할 수 있습니다.

3. TypeScript 또는 JSX 사용

로컬 패키지에 TypeScript 또는 JSX와 같은 언어로 작성된 코드가 포함되어 있다면, Next.js는 이를 트랜스파일링 대상으로 간주하지 않습니다. 이런 경우 해당 패키지를 transpilePackages에 추가해 Next.js의 Babel 설정으로 트랜스파일해야 합니다.

4. 배포 환경에서의 문제

Next.js는 node_modules를 서버와 클라이언트에서 각각 다르게 처리합니다. 만약 로컬 패키지에 최신 문법이 포함되어 있고, 이를 트랜스파일하지 않으면 특정 브라우저(구형 브라우저 등)에서 코드가 정상적으로 작동하지 않을 수 있습니다.

해결책 transpilePackages 사용

transpilePackages는 특정 패키지(로컬 또는 외부)를 Next.js의 Babel 트랜스파일 파이프라인에 포함시키도록 명시하는 옵션입니다. 예:

// next.config.js
const nextConfig = {
  transpilePackages: ['my-local-package', 'another-package'],
};

module.exports = nextConfig;

이렇게 하면:

1. Next.js는 해당 패키지를 Babel로 트랜스파일합니다.

2. TypeScript, JSX, ES6+ 문법 등이 트랜스파일되어 브라우저와 서버에서 정상적으로 실행됩니다.

3. 코드 호환성과 실행 안정성이 보장됩니다.

결론

transpilePackages를 사용하는 이유는 Next.js의 성능 최적화 기본 동작과 로컬/외부 패키지의 최신 코드가 충돌하는 문제를 해결하기 위해서입니다. 이를 통해 모든 환경에서 일관되게 동작하는 애플리케이션을 만들 수 있습니다.