npm 스크립트로 작업 자동화하기

npm 스크립트란

package.json의 scripts에 이름과 명령을 적어 두고 npm run <이름>으로 실행한다. 별도 도구 없이 린트·테스트·빌드·배포 명령을 프로젝트에 붙박아 두는 가장 얇은 작업 실행기다. 의존성을 설치하는 쪽 이야기는 자바스크립트 패키지 매니저에 있다.

{
  "scripts": {
    "dev": "vite",
    "build": "tsc --noEmit && vite build",
    "lint": "eslint .",
    "test": "vitest run",
    "test:watch": "vitest"
  }
}

기능

수명 주기 스크립트

이름이 정해진 스크립트는 npm 명령이 알아서 부른다.

prepublish는 publish와 install 양쪽에서 돌아 혼란을 일으켜 폐기됐고 prepare·prepublishOnly로 나뉘었다. 의존성의 설치 스크립트는 공급망 공격 통로이기도 해서 매니저마다 기본값으로 막는 추세다. 자세한 것은 패키지 매니저의 공급망 보안 절에 있다.

작업 조합하기

&&, |, >, <는 POSIX 셸과 cmd.exe에서 같게 동작한다. 이 넷만 쓰고 나머지는 npm 패키지나 Node 스크립트로 해결하면 OS를 가리지 않는다.

스크립트가 한 줄에 다 안 들어가기 시작하면 Node 스크립트 파일로 뺀다. JSON 문자열 안의 긴 셸 명령은 이스케이프가 지저분하고 주석도 달 수 없다.

실행기마다 다른 점

훅이나 npm_package_* 변수에 기대는 스크립트는 실행기를 바꾸면 조용히 다르게 동작한다. 팀이 쓰는 매니저를 packageManager 필드로 고정한다.

태스크 러너가 밀려난 이유

2010년대 중반까지 프런트엔드 빌드는 Grunt(2012, JSON 같은 설정으로 작업 정의, 단계마다 임시 파일을 디스크에 썼다)와 Gulp(2013, 코드로 작업 정의)가 맡았다.

Gulp의 설계는 이렇다.

npm 스크립트로 옮겨 간 이유는 추상화 한 겹의 비용이었다.

1. 플러그인 작가에게 묶인다. 도구(예: Babel 6)가 API를 바꾸면 gulp-babel이 따라올 때까지 새 버전을 못 쓴다. 플러그인이 원래 도구 API의 일부만 노출하기도 한다.
2. 디버깅 지점이 늘어난다. 도구 문제인지, 플러그인 문제인지, 설정 문제인지, 버전 불일치인지 가려야 한다.
3. 문서가 둘로 갈린다. gulp-eslint 문서와 ESLint 문서를 오가야 한다. 대부분의 도구는 CLI 문서가 가장 잘 정리돼 있다.
4. 스트림 속도가 필요하다는 생각은 셸 파이프로, 크로스 플랫폼 걱정은 rimraf·cross-env 같은 작은 패키지로 풀렸다.

생태계 쪽 교훈도 남았다. Gulp는 잡동사니 유틸을 모은 gulp-util을 폐기하며 플러그인들에게 fancy-log, plugin-error, vinyl 같은 한 가지 일만 하는 작은 모듈로 옮기라고 했다. 수천 개 플러그인이 낡은 공용 패키지에 묶여 있으면 코어를 바꿀 때 생태계 전체가 깨진다.

지금은 번들러·개발 서버(Vite, webpack)가 변환·감시·새로고침을 맡고, npm 스크립트는 그 명령을 이름 붙여 묶는 역할만 한다. Gulp는 5판(2024)까지 유지되지만 새 프로젝트의 기본 선택은 아니다. 모노레포에서 패키지 간 작업 순서와 캐시가 필요해지면 Turborepo·Nx 같은 작업 오케스트레이터를 npm 스크립트 위에 올린다(모노레포와 폴리레포).

정리

• npm 스크립트는 node_modules/.bin이 PATH에 들어간 셸에서 명령을 실행한다. 도구는 전역이 아니라 devDependencies로 깐다.
• -- 뒤 인자는 그대로 넘어가고, pre/post 훅과 수명 주기 스크립트(prepare, prepublishOnly)가 있다.
• 동시 실행·파일 삭제·환경 변수는 OS마다 달라서 run-p, rimraf, cross-env나 Node 스크립트로 푼다.
• yarn(Berry)과 node --run은 임의 pre/post 훅을 돌리지 않는다. 훅에 기대지 않는 스크립트가 이식성이 높다.
• 태스크 러너가 밀려난 핵심은 도구를 플러그인으로 감싼 한 겹의 추상화였다. 도구의 CLI를 바로 부른다.

관련 노트: 자바스크립트 패키지 매니저: npm, yarn, pnpm, 번들러의 역사와 Vite, webpack 동작 원리, ESLint와 Prettier 설정, 모노레포와 폴리레포