React Module not found: Can't resolve 뒤 이름부터 구분하세요

AI 코딩 도구가 React 화면을 만들어 줬는데 npm run dev를 켜자마자 Module not found 또는 Can't resolve가 뜰 때가 있습니다. 초보자는 이 순간에 "AI가 코드를 망가뜨렸다"거나 "프로젝트를 다시 만들어야 하나"라고 느끼기 쉽습니다. 하지만 이 에러는 대부분 전체 구조 문제가 아니라 가져오려는 패키지나 파일을 빌드 도구가 찾지 못한 상태입니다.

먼저 할 일은 코드를 다시 생성하는 것이 아닙니다. 에러 첫 줄에 나온 이름이 패키지인지 파일 경로인지를 구분해야 합니다. 이 구분만 해도 npm install로 끝날 문제와 import 경로를 고쳐야 할 문제가 나뉩니다.

Tap to zoom

nextjs.org의 공식 오류 문서는 Module not found의 대표 원인으로 의존성 누락, 패키지 이름 오류, 존재하지 않는 로컬 파일 import를 설명합니다. docs.npmjs.com의 npm install 문서도 npm install <package-spec>가 패키지를 설치하고 기본적으로 dependencies에 저장한다고 안내합니다. 그래서 이 문제는 감으로 라이브러리를 지우는 문제가 아니라, 설치와 경로를 순서대로 나누는 문제입니다.

에러 첫 줄에서 이름을 분리합니다

터미널에서 먼저 이 줄을 찾습니다.

Module not found: Can't resolve 'lucide-react'
Module not found: Can't resolve './components/Header'
Module not found: Can't resolve '@/lib/utils'

따옴표 안의 값이 판단 기준입니다. lucide-react, axios, clsx처럼 점이나 슬래시 없이 이름만 있으면 보통 패키지 문제입니다. ./components/Header, ../lib/api, @/lib/utils처럼 경로 모양이면 보통 파일 경로, 별칭, 대소문자 문제입니다.

AI에게도 이 이름을 그대로 줘야 합니다.

React 앱 실행 중 Module not found가 납니다.
에러 줄은 "Can't resolve 'lucide-react'"입니다.
전체 코드를 다시 만들지 말고 이 import가 패키지인지 로컬 파일인지 먼저 구분해 주세요.
필요한 경우 package.json과 import 줄만 확인해 주세요.

이 프롬프트의 핵심은 전체 수정 금지입니다. Module not found 하나 때문에 AI가 라우터, 폴더 구조, UI 컴포넌트를 함께 바꾸기 시작하면 원인이 더 흐려집니다.

패키지 이름이면 설치 상태를 확인합니다

에러 이름이 패키지라면 package.json의 dependencies부터 봅니다. 예를 들어 에러가 Can't resolve 'lucide-react'인데 package.json에 lucide-react가 없다면 설치가 먼저입니다.

npm install lucide-react

설치 뒤에는 다시 실행합니다.

npm run dev

여기서 초보자가 자주 하는 실수는 AI가 예시 코드에 넣은 라이브러리를 프로젝트에 이미 있다고 생각하는 것입니다. 아이콘 예시에는 lucide-react, 스타일 유틸에는 clsx, 날짜 예시에는 date-fns가 들어갈 수 있습니다. import 줄이 생겼다고 패키지가 자동 설치되는 것은 아닙니다.

아래처럼 먼저 확인합니다.

에러 이름: lucide-react
package.json dependencies에 있는가: 없음
해결 후보: npm install lucide-react

반대로 이미 설치돼 있는데도 같은 에러가 나면 패키지 이름 오타를 봅니다. lucide-react를 lucid-react로 썼거나, 라이브러리 문서의 import 이름을 잘못 옮긴 경우가 있습니다.

파일 경로면 위치와 대소문자를 확인합니다

에러 이름이 ./components/Header처럼 경로라면 설치 문제가 아닙니다. 이때는 실제 파일이 있는지 봅니다.

import Header from "./components/Header";

위 import가 있다면 아래 후보를 확인합니다.

src/components/Header.tsx
src/components/Header.jsx
src/components/header.tsx
src/component/Header.tsx

Windows에서는 대소문자가 달라도 로컬에서 우연히 동작하는 경우가 있습니다. 하지만 배포 환경이나 일부 파일 시스템에서는 Header.tsx와 header.tsx를 다르게 봅니다. 그래서 로컬에서는 되는데 Vercel 빌드에서만 깨진다면 파일명 대소문자부터 맞춥니다.

경로 별칭도 따로 봐야 합니다.

import { cn } from "@/lib/utils";

@/ 별칭을 쓰려면 보통 tsconfig.json 또는 jsconfig.json의 paths 설정과 빌드 도구 설정이 맞아야 합니다. typescriptlang.org의 module resolution 문서처럼 TypeScript는 설정에 따라 모듈을 찾는 방식이 달라질 수 있습니다. 별칭 설정이 없는 프로젝트라면 상대 경로로 바꾸거나 별칭 설정을 추가해야 합니다. 다만 초보 단계에서는 먼저 실제 파일이 있는지, 파일명이 정확한지, import가 현재 파일 위치 기준으로 맞는지 확인하는 편이 빠릅니다.

Tap to zoom

서버 전용 코드를 브라우저 코드에서 import했는지 봅니다

설치도 되어 있고 파일 경로도 맞는데 에러가 계속 나면 import 위치를 봅니다. React 클라이언트 컴포넌트나 Vite 브라우저 코드에서 Node.js 전용 모듈을 가져오면 문제가 됩니다.

예를 들어 브라우저 화면 컴포넌트에서 아래처럼 쓰면 안 됩니다.

import fs from "fs";
import path from "path";

nodejs.org의 ECMAScript modules 문서는 import specifier와 파일 경로 해석을 별도로 다룹니다. fs와 path는 Node.js 서버 환경에서 쓰는 모듈입니다. 브라우저에서 렌더링되는 React 컴포넌트가 파일 시스템을 직접 읽을 수는 없습니다. 이 경우 해결은 npm install fs가 아닙니다. 코드를 서버 쪽 API, Next.js 서버 컴포넌트, 빌드 스크립트 등 적절한 위치로 옮겨야 합니다.

AI에게는 이렇게 제한해서 요청합니다.

React 브라우저 컴포넌트에서 Module not found가 납니다.
import 목록에 fs, path, crypto 같은 Node.js 전용 모듈이 있는지 확인해 주세요.
패키지를 억지로 설치하지 말고 서버 코드와 브라우저 코드를 분리하는 최소 수정만 제안해 주세요.

여기서 중요한 기준은 설치하면 되는 모듈인지, 브라우저에서 쓰면 안 되는 모듈인지입니다. 둘을 섞으면 해결이 늦어집니다.

설치 뒤에도 안 되면 dev 서버와 캐시를 새로 봅니다

패키지를 설치했는데 같은 에러가 남을 때는 dev 서버를 그대로 켜 둔 상태인지 확인합니다. vite.dev의 의존성 사전 번들링 문서는 개발 중 의존성 감지와 처리 흐름을 설명하지만, 초보자가 보기에는 dev 서버를 재시작하는 것이 가장 빠른 확인입니다.

Ctrl + C
npm run dev

그래도 안 되면 lockfile과 설치 상태를 확인합니다.

npm install
npm run build

npm run dev는 개발 서버 확인이고, npm run build는 배포 전 확인입니다. 로컬 화면이 켜져도 build에서 import 문제가 드러날 수 있습니다. 특히 대소문자 문제와 별칭 문제는 배포 직전에 발견되는 경우가 많습니다.

AI에게는 결과를 나눠서 줍니다.

npm install은 성공했습니다.
npm run dev는 [성공/실패]이고 npm run build는 [성공/실패]입니다.
같은 Module not found가 남는다면 설치 문제와 import 경로 문제를 분리해서 봐 주세요.
관련 없는 컴포넌트 리팩터링은 하지 마세요.

AI에게 붙여 넣을 7줄 프롬프트

아래 프롬프트를 그대로 채우면 AI가 문제를 크게 흔들지 않고 필요한 파일부터 보게 만들 수 있습니다.

React 앱에서 Module not found 또는 Can't resolve 오류가 납니다.
에러 줄은 "[여기에 Can't resolve 전체 줄]"입니다.
이 이름이 npm 패키지인지 로컬 파일 경로인지 먼저 구분해 주세요.
패키지라면 package.json dependencies와 정확한 패키지명을 확인해 주세요.
로컬 파일이라면 실제 파일 위치, import 상대 경로, 대소문자를 확인해 주세요.
브라우저 컴포넌트에서 Node.js 전용 모듈을 import한 경우도 확인해 주세요.
전체 구조를 다시 만들지 말고 필요한 최소 수정과 확인 명령만 제안해 주세요.

이 프롬프트의 목적은 정답을 한 번에 맞히는 것이 아닙니다. AI가 확인 순서를 지키게 만드는 것입니다. Module not found는 같은 문구로 보여도 패키지 누락, 경로 오타, 대소문자, 별칭 설정, 서버 전용 코드 혼입이 모두 다른 처방을 요구합니다.

오류가 사라진 뒤 화면이 비어 있다면 문제는 모듈 해석에서 렌더링 단계로 넘어간 것입니다. 이때는 React 빈 화면에서 콘솔부터 확인하는 순서로 다음 원인을 좁힙니다. AI가 수정 범위를 계속 넓힌다면 오류·파일·환경·검증 결과를 나눠 다시 질문하는 법을 함께 적용하면 관련 없는 변경을 줄일 수 있습니다.

마지막으로 오늘 할 일은 하나입니다. 에러 줄의 따옴표 안 이름을 복사하고, 패키지인지 경로인지 표시합니다. 패키지면 package.json을 보고 설치합니다. 경로면 실제 파일명과 대소문자를 맞춥니다. 그 다음 dev 서버를 재시작하고 npm run build까지 확인합니다. 이 순서를 지키면 "AI가 만든 코드를 다시 만들어 달라"는 요청을 하기 전에, 고칠 지점이 훨씬 작아집니다.

참고 출처

• Next.js Module Not Found: https://nextjs.org/docs/messages/module-not-found
• npm install: https://docs.npmjs.com/cli/install/
• Vite Dependency Pre-Bundling: https://vite.dev/guide/dep-pre-bundling
• Node.js ECMAScript Modules: https://nodejs.org/api/esm.html
• TypeScript Module Resolution: https://www.typescriptlang.org/docs/handbook/modules/reference.html#the-moduleresolution-compiler-option

이 글은 AI 코딩과 개발 학습의 일반 정보 제공 목적입니다. 도구, 모델, 커리큘럼, 요금은 버전과 시점에 따라 달라질 수 있으므로 실습이나 도입 전 공식 문서와 최신 릴리스 노트를 확인하세요.