빠른 설정

package.json의 scripts는 단순 단축키가 아니라, 프로젝트의 공식 진입점을 정하는 자리입니다.

{
  "type": "module",
  "scripts": {
    "dev": "node --watch src/index.js",
    "build": "tsc",
    "test": "node --test"
  }
}

여기서 핵심은 필드 이름 암기보다 "팀이 무엇을 표준 명령으로 쓸 것인가"를 정하는 데 있습니다.

스크립트 실행

먼저 구분해 둘 기본형은 아래입니다.

• 팀 표준 명령: scripts
• 로컬 CLI 실행: npm run
• 전후 훅: pre* / post*
• 일회성 생성기: npx
• 모듈 해석 영향: "type"

왜 npm run이 중요한가

npm run은 로컬 node_modules/.bin을 PATH에 넣고 실행합니다. 그래서 전역 설치 없이 프로젝트가 기대하는 버전의 CLI를 바로 쓸 수 있습니다.

이게 중요한 이유는:

• 팀원이 같은 도구 버전을 쓰게 됨
• CI와 로컬 명령이 맞춰짐
• README에 실행 규칙을 단순하게 적을 수 있음

훅 구성

pre / post 훅은 흐름 분리용

{
  "scripts": {
    "pretest": "npm run lint",
    "test": "node --test",
    "posttest": "node scripts/report.js"
  }
}

이 패턴은 쉘 명령을 한 줄로 길게 엮는 것보다 역할이 더 잘 보입니다.

• 본 작업
• 전처리
• 후처리

scripts는 결국 프로젝트 명령을 구조화하는 자리이기도 합니다.

실행 도구

npm run vs npx

• 프로젝트 표준 명령: npm run
• 일회성 실행/생성기: npx

이 구분을 먼저 잡아 두면 스크립트 설계가 깔끔해집니다.

npm run build
npx create-vite@latest

이미 프로젝트 안에 정해 둔 명령은 npm run으로 묶고, 일회성 생성기나 단발성 실행은 npx로 분리하는 편이 흐름이 선명합니다.

scripts는 "자주 쓰는 공식 진입점"만 남기는 편이 좋다

스크립트를 다 넣는다고 좋은 게 아니라, 팀이 반복해서 쓰는 개발·빌드·테스트·배포 진입점이 바로 보여야 합니다. 세부 조합이 너무 많아지면 scripts는 설명서가 아니라 추측 게임이 되기 쉽습니다.

언제 훅을 붙일까

scripts를 설계할 때 볼 점

• 프로젝트 표준 진입점은 scripts
• 로컬 CLI 실행은 npm run
• 전후 작업은 pre* / post*
• 일회성 도구는 npx
• type 필드는 모듈 해석 방식에 직접 영향
• scripts는 자주 쓰는 공식 진입점만 남기는 편이 낫다

스크립트가 많은데 npm run 목록만 봐도 무엇이 공식 진입점인지 안 보이면, 명령은 늘었지만 구조는 나빠진 상태라고 보면 됩니다.

주의할 점