1. 상황

보류했던 프로젝트(Next.js 14.2.3 + HeroUI)를 다시 열어 로컬에서 돌려 보려고 했다. 그런데 npm run dev부터 이렇게 나왔다.

npm run dev
> next dev
sh: next: command not found

next가 없다는 건 설치가 끝난 적이 없다는 뜻이다. npx install next도 해 봤지만 could not determine executable to run만 나왔다. 결국 npm install부터 다시 봐야 했다.

2. 첫 번째 벽: ERESOLVE

npm install은 이 에러로 멈췄다. (핵심 줄만 남겼다)

npm error code ERESOLVE
npm error While resolving: next-app-template@0.0.1
npm error Found: eslint@8.56.0
npm error Could not resolve dependency:
npm error peer eslint@"^3 || ^4 || ^5 || ^6 || ^7" from eslint-plugin-jsx-a11y@6.4.1

AI가 짚은 원인은 이랬다. eslint-plugin-jsx-a11y@6.4.1이 ESLint 7 이하만 지원하는데 프로젝트는 ESLint 8.56.0을 쓰고 있어서 의존성 트리가 맞지 않는다는 것이다. 해결 방법은 두 가지가 나왔다.

• 방법 1(추천): 플러그인 버전을 올린다. npm install -D eslint-plugin-jsx-a11y@^6.9.0 (6.5 이후부터 ESLint 8 지원)
• 방법 2: 충돌을 무시하고 일단 설치만 한다. npm install --legacy-peer-deps

이 에러는 린트 플러그인 문제라서 사이트 동작과는 무관하고, npm run lint를 돌릴 때만 영향이 있다고 했다. 실제로 내 터미널 기록을 보면 --legacy-peer-deps로 넘어갔다.

[보강: 방법 1(버전 올리기) 대신 방법 2를 쓴 이유]

3. 두 번째 벽: ETARGET

ESLint 충돌은 넘어갔는데 이번엔 다른 에러가 나왔다.

npm error code ETARGET
npm error notarget No matching version found for @heroui/button@2.0.38.

원인은 버전 번호였다. 2.0.38은 예전 @nextui-org/button의 버전이다. 패키지 이름만 @nextui-org/*에서 @heroui/*로 바꾸고 버전 번호는 그대로 둔 상태였는데, @heroui/*는 버전이 새로 시작해서 그 번호가 npm에 없다.

여기서 하나 눈에 띈 게 있다. AI가 처음 받은 package.json에는 @nextui-org/*만 있었다. 즉 AI가 본 코드와 내 로컬 코드가 달랐다. 로컬은 이미 HeroUI로 바꾼 최신 버전이었고, 에러 로그를 그대로 붙여 넣은 덕분에 그 차이가 드러났다.

해결은 @heroui/* 버전을 한꺼번에 latest로 바꾸는 것이었다. macOS 기준 명령이다(sed -i ''는 macOS 문법).

grep -n "heroui\|nextui" package.json
sed -i '' -E 's#("@heroui/[^"]+": )"[^"]+"#\1"latest"#' package.json
npm install --legacy-peer-deps

이번에는 설치가 끝났다. added 669 packages, 2분쯤 걸렸다.

다만 latest는 임시방편이다. AI는 설치가 되면 npm ls @heroui/react로 실제 설치된 버전을 확인하고, latest 대신 그 버전으로 고정해서 커밋하라고 했다. 이 프로젝트에는 .npmrc에 package-lock=false가 있어서 package-lock.json이 생성되지 않고, 설치할 때마다 버전이 달라질 수 있기 때문이다. 그 줄을 지우고 lock 파일을 커밋해 두면 이런 재현 문제가 줄어든다.

4. 세 번째: 설치는 됐는데 404

서버는 떴다. 그런데 화면은 404였다.

▲ Next.js 14.2.3
 ✓ Ready in 2.9s
 ○ Compiling /_not-found ...
 GET / 404 in 1474ms

AI의 설명은 이랬다. Ready는 서버가 떴다는 뜻이고, 404는 / 경로에 해당하는 페이지를 못 찾았다는 뜻이다. 의존성과는 별개의 문제이고 거의 항상 app/page.tsx를 못 찾을 때 나온다. 확인할 것은 세 가지였다.

• app/page.tsx가 없거나 app/이 비어 있다: git status에 D app/page.tsx처럼 삭제 표시가 있으면 git restore app/page.tsx
• src/app/이 따로 있다: 루트에 app/이 있으면 Next는 그것만 보고 src/app은 무시하므로 하나로 합쳐야 함
• app/page.tsx가 있는데도 404: rm -rf .next 후 npm run dev로 캐시 제거

ls app
ls src 2>/dev/null
git status --short | head -20

이 대화는 여기서 끝났다. 위 명령의 결과를 붙여 넣기 전이라, 404의 실제 원인은 아직 확정되지 않았다.

[보강: ls app과 git status --short 결과, 그리고 404의 실제 원인과 해결]

같이 나온 경고도 기록해 둔다.

• 21 vulnerabilities가 뜨지만 npm audit fix --force는 하지 않기로 했다. 버전이 크게 바뀌어 프로젝트가 깨질 수 있다
• next@14.2.3은 보안 패치가 나온 버전이라는 경고가 떴다. 사이트가 돌아간 뒤 최신 14.2.x로 올릴 예정이다
• main* 표시는 커밋 안 된 변경이 있다는 뜻이다. sed로 package.json을 바꿨으니 동작 확인 후 커밋한다

정리

• ERESOLVE는 peer 의존성 충돌이다. 버전을 올리는 게 정석이고, --legacy-peer-deps는 일단 넘어가는 우회다
• 패키지 이름이 바뀐 라이브러리(@nextui-org → @heroui)는 버전 번호도 새로 확인한다
• AI가 본 파일과 내 로컬 파일은 다를 수 있다. 에러 로그를 그대로 붙여야 차이가 빨리 드러난다
• Ready가 떠도 404가 나올 수 있다. 라우팅 문제이고, app/page.tsx부터 확인한다
• lock 파일이 없으면 설치할 때마다 버전이 달라질 수 있다

다음 글 예고

이 옛 코드를 이어 가는 대신 웹을 새로 만들기로 한 뒤, 새 웹을 집 서버에 git push 한 번으로 배포한 이야기를 쓴다.