npx 이해하기: 실제 작동 방식

Source: Dev.to

Summary

이 글은 npx를 두 단계로 설명합니다:

• 정확한 해석 단계가 포함된 간략 개요
• 각 단계에 대한 깊이 있는 설명

Overview

npx는 실행 파일을 찾아 실행합니다.
실행 파일이 로컬이나 전역에 없으면 일시적으로 다운로드하여 실행합니다.

npx를 실행 파일 해석기로 생각하면 되며, 패키지 매니저가 아닙니다.

Exact Resolution Order (Quick Scan)

What npx does?
Searches for a file and executes it.

Search Step-1
    Searches for package.json in current working directory
    Searches for name key in the json
    Searches for bin key

Search Step-2
    Searches for node_modules/.bin/hello in current working directory
    And executes this file

Search Step-3
    Searches for hello in global npm folder
    And executes this file

Search Step-4
    Searches for hello package in npx cache
    And executes this file

Search Step-5
    Searches for hello package in npm registry
    Prompts to install the package if found
    Downloads and installs

일치하는 항목을 찾으면 즉시 실행을 중단합니다.

Deep Explanation: How Each Step Works

Step 1: Project package.json — Project‑Scoped CLI

npx는 현재 디렉터리에 package.json이 있는지 확인하고 name과 bin 필드를 검사합니다.

{
  "name": "hello",
  "bin": {
    "hello": "./index.js"
  }
}

명령 이름이 name과 일치하고 bin 필드가 같은 명령을 노출하면, npx는 매핑된 파일을 직접 실행합니다.

왜 중요한가
프로젝트 수준의 CLI를 설치 없이 사용할 수 있게 해 주며, 전역에 설치된 도구에 의존하지 않게 합니다.

Step 2: Local node_modules/.bin (Preferred Execution)

Step 1이 실패하면 npx는 로컬 바이너리 폴더에서 실행 파일을 찾습니다:

./node_modules/.bin/hello

이 폴더는 bin 필드를 선언한 의존성을 npm이 설치할 때 자동으로 생성됩니다.

npm install hello-cli   # creates node_modules/.bin/hello
npx hello                # executes that file

핵심 규칙
로컬 프로젝트용 실행 파일은 항상 전역 파일보다 우선합니다.

Step 3: Global npm Binary Folder

로컬 실행 파일이 없으면 npx는 전역 npm 바이너리 디렉터리를 확인합니다:

npm bin -g   # e.g., /usr/local/bin

hello가 그곳에 있으면 npx가 실행합니다.

우선순위가 낮은 이유
전역 CLI는 프로젝트마다 버전 불일치를 일으킬 수 있기 때문에, npx는 로컬 도구를 우선시합니다.

Step 4: npx Cache — Fast Reuse

여전히 찾지 못하면 npx는 내부 캐시로 넘어갑니다. 캐시는:

• 이전에 다운로드한 CLI 패키지를 저장
• 중복 다운로드 방지
• 반복 작업 실행 속도 향상

캐시는 npm에 의해 관리되며 npm 내부와 공유됩니다.

Step 5: npm Registry (Last Resort)

이전 단계가 모두 실패하면 npx는 npm 레지스트리를 조회합니다. hello라는 패키지가 존재하면:

1. 패키지를 다운로드한다.
2. bin 항목을 해석한다.
3. 실행 파일을 즉시 실행한다.
4. 향후 사용을 위해 패키지를 캐시한다.

예시:

npx create-react-app my-app

전역 설치가 일어나지 않으며, package.json에도 저장되지 않습니다.

Mental Model to Remember

npx = 실행 파일을 해석하는 것이지, 의존성을 설치하는 것이 아닙니다.
설치는 해석에 실패했을 때만 발생합니다.

Final Takeaway

npx는 명령 실행기입니다:

• 로컬 프로젝트 도구가 항상 우선
• 전역 도구는 보조 역할
• 캐시가 재다운로드를 방지
• 레지스트리 조회는 최후의 수단

다음 상황에서 npx를 사용하세요:

• 일회성 CLI 사용이 필요할 때
• 전역 설치를 피하고 싶을 때
• 버전 안전성을 보장하고 싶을 때
• 깨끗한 개발 환경을 유지하고 싶을 때

Questions to Think About

Q1: 버전을 지정하지 않으면, npx는 어떤 버전을 다운로드해야 할지 어떻게 알까요?

Q2: 같은 명령이 로컬과 전역에 모두 존재한다면 어떻게 될까요?

Q3: npx 해석 과정에서 node_modules/.bin이 전역 바이너리보다 선호되는 이유는 무엇일까요?