AntD와 Next.js 12, 14

억울해서 남기는 삽질기록...

지난 포스트에 달았던 댓글에서 볼 수 있듯이 TypeScript, ESLint, Tailwind CSS 등을 일일히 세팅하지 않아도 최신 버전의 create-next-app 에서는 자동으로 설치를 해 준다.

kwonkyu@kwonkyu-CodingMusin:~/Projects/BackOffice-Demo$ npx create-next-app
Need to install the following packages:
create-next-app@14.2.15
Ok to proceed? (y)

✔ What is your project named? … backoffice-demo
✔ Would you like to use TypeScript? … No / Yes
✔ Would you like to use ESLint? … No / Yes
✔ Would you like to use Tailwind CSS? … No / Yes
✔ Would you like to use `src/` directory? … No / Yes
✔ Would you like to use App Router? (recommended) … No / Yes
✔ Would you like to customize the default import alias (@/*)? … No / Yes
Creating a new Next.js app in /home/kwonkyu/Projects/BackOffice-Demo/backoffice-demo.

Using npm.

Initializing project with template: default-tw 


Installing dependencies:
- react
- react-dom
- next

Installing devDependencies:
- typescript
- @types/node
- @types/react
- @types/react-dom
- postcss
- tailwindcss
- eslint
- eslint-config-next
...

여기서 TypeScript, ESLint, Tailwind CSS, `src/` directory 옵션에 Yes를 선택하고 나머지 App Router 등은 No를 선택하면 정말 귀신같이 알아서 세팅이 된다. 그런데 막상 AntD 라이브러리 의존성을 추가해서 사용하니 다음과 같은 에러가 발생한다.

회사에서 사용할 때는 한번도 발생한 적이 없는 에러라 대체 뭐가 문제인가... 곰곰히 생각해봤는데 최신 버전의 create-next-app을 쓰면서 Next.js 버전을 14로 사용하고 있던 게 생각났다. 관련해서 이슈를 찾아보니 이미 깃헙에서도 수많은 사람들이 재현중이며 원인은 대충 읽어보면 최신 버전의 Next.js에서 사용하는 pages-router가 모듈을 임포트하는 방식이 달라서 그렇다는 것 같다. 12버전까지 사용하던게 pages-router고 13버전부터 더 개선된 버전인 app-router가 사용되고 있는데 이 antd 라이브러리를 임포트할 때 ECMAScript module 방식과 CommonJS 방식이 상충되어 발생하는 것 같다.

일단 지금까지의 해결 방법으로는 트랜스파일 설정을 추가하거나 그냥 리액트 버전을 낮추는 것이 있는데 나는 이 프로젝트의 원래 목적대로 회사 버전인 12에 맞춰 낮추기로 했다. 트랜스파일에 대해서는 잘 모르지만 깃헙 이슈에서도 그렇고 위의 에러 콜스택을 잘 보면 node_modules 하위의 특정 자바스크립트 파일을 읽다가 에러가 발생하고 있다. 그래서 이 파일의 패키지 이름을(위의 로그에서는 rc-util) 일일히 Next.js 설정 파일의 transpilePackages 값에 추가하는 식으로 해결하고 있는 것 같다.

그래서 저 위에 나온 rc-util 부터 시작해서 에러가 안 뜰때까지 패키지 이름을 추가하다 보면 지금 상태로는 저 4개 정도로 antd 컴포넌트를 그릴 수 있게 된다. 그렇지만 혹시나? 하는 마음이거나 또는 실제로 사용하다가 문제가 있었기 때문에 해당 깃헙 이슈에서는 이런저런 패키지를 추가한 것 같다. 어쨌든 이것도 out-of-the-box하게 해결되는 방식은 아닌 데다가 앞으로도 프로젝트를 진행하다가 비슷한 이슈를 만나면 좀 짜증날 것 같아서 12 버전으로 내려서 진행하기로 했다.

...근데 버전을 내려도 비슷한 에러가 발생한다? 다행히 이 경우는 컴포넌트를 임포트하는 경로를 다르게 해주면, 정확히는 es 경로를 사용하지 않으면 해결되는 문제였다.

import { Cascader } from "antd";           // 정상 작동
import Cascader from "antd/lib/cascader";  // 위의 에러 발생
import Cascader from "antd/es/cascader";   // 위의 에러 발생

이것도 깃헙 이슈를 참고하면 크게 신경쓸 건 아니라고 하는데 tree-shaking, bundler 등의 얘기가 나오는 걸 보면 나중에 빌드할 때 최적화에 관련된 내용인 것 같다. 그런데 얘도 결국은 트랜스파일을 사용해야 해결할 수 있는 모양이다. 블로그에서 설명하는 방식은 Next.js 문서를 참고하면 결국 위의 transpilePackages 를 활용하는 방식인데 회사 프로젝트에서도 비슷한 문제가 있어서 lib 디렉토리 하위의 컴포넌트를 임포트하는 걸로 해결했던 것 같다.

이 트랜스파일이 뭐길래 이렇게 귀찮게 하고 왜 필요한 건지, 특히 왜 AntD를 사용할 때 트랜스파일 관련해서 문제가 되는건지 나중에 좀 알아봐야 할 것 같다.
(읽어볼 링크 #1)
(읽어볼 링크 #2)