npm install을 통해 설치한 패키지를 import할 때, Node.js와 빌드 도구들이 해당 파일을 찾아내는 과정은 Node.js의 모듈 해소(Module Resolution) 알고리즘을 따릅니다.
상대 경로(./, ../) 없이 패키지 이름만 적었을 때 일어나는 일을 단계별로 정리해 드릴게요.
1. node_modules 탐색
가장 먼저 실행 파일이 위치한 디렉토리에서 node_modules 폴더를 찾습니다.
- 만약 현재 디렉토리에 없다면? 상위 디렉토리로 올라가서
node_modules를 다시 찾습니다. - 이 과정은 루트 디렉토리(
/)에 도달할 때까지 반복됩니다. - 패키지를 찾으면 해당 폴더(
node_modules/package-name)로 진입합니다.
2. package.json 확인 (진입점 찾기)
패키지 폴더 안에 들어오면, 이 패키지의 “대문”이 어디인지 확인하기 위해 package.json 파일을 읽습니다. 이때 아래 필드들을 순서대로 확인합니다.
exports: 최신 표준입니다. 외부에서 어떤 경로로 들어왔을 때 어떤 파일을 보여줄지 정밀하게 정의합니다.module: ESM(ECMAScript Modules) 방식의 진입점을 가리킵니다. (React, Vue 등 최신 라이브러리에서 주로 사용)main: CommonJS 방식의 기본 진입점입니다. (주로index.js)
3. 기본 파일 로딩 (Fallback)
만약 package.json에 진입점 설정이 없거나 파일이 없다면, Node.js는 약속된 기본값을 찾습니다.
index.jsindex.jsonindex.node(컴파일된 바이너리)
요약 프로세스
예를 들어 import axios from 'axios'를 실행하면 다음과 같은 논리가 작동합니다.
| 단계 | 동작 |
| Step 1 | 현재 폴더의 node_modules/axios가 있는지 확인 |
| Step 2 | 없다면 상위 폴더의 node_modules/axios 확인 (반복) |
| Step 3 | axios/package.json을 열어 main 또는 exports 경로 확인 |
| Step 4 | 지정된 파일(예: dist/axios.js)을 메모리에 로드 |
💡 팁: 왜 이렇게 복잡하게 찾나요?
이런 방식 덕분에 우리는 프로젝트의 어느 깊숙한 폴더에 있더라도 ../../node_modules/package 처럼 복잡하게 경로를 쓰지 않고, 단지 이름만으로 패키지를 불러올 수 있는 것입니다.
만약 번들러(Webpack, Vite)를 사용 중이라면 이 과정에 ‘Alias(별칭)’나 ‘브라우저 최적화 경로’가 추가되기도 하지만, 기본 골자는 위와 같습니다.