유원의 일기

리액트 프로젝트를 클론한 후 로컬에서 실행하려고 npm start 명령어를 입력하면서 문득 npm start와 npm run start 명령어가 같은 의미인지 궁금해졌다.

자바스크립트 프로젝트에서 개발을 하다 보면, 로컬 서버 실행, 테스트, 빌드 등 반복 작업을 위해 터미널에서 명령어를 자주 입력하게 된다. 이런 작업들을 스크립트로 등록해 두면 훨씬 편리하다.

이번 글에서는 npm start와 npm run start의 차이를 살펴보고, 자주 사용하는 반복 작업을 어떻게 스크립트로 등록하고 실행하는지도 함께 정리해 보자.

🤔 npm start vs npm run start

결론부터 말하면 npm start는 npm run start의 축약형이다. npm start는 package.json 파일의 scripts 항목 중 "start"에 정의된 명령어를 실행한다. npm run start도 동일한 방식으로 동작한다.

⚠️ "start"는 특별한 예약어라 npm run을 생략할 수 있지만, "build", "test", "dev" 등 다른 스크립트는 반드시 npm run <스크립트명> 형태로 실행해야 한다.

🛠️ 스크립트를 등록하는 이유

리액트 프로젝트뿐 아니라 대부분의 프런트엔드/백엔드 자바스크립트 프로젝트는 다양한 CLI 명령어를 사용한다.

• 테스트: jest, vitest, mocha 등
• 빌드: webpack, vite, parcel 등
• 린트: eslint
• 포맷팅: prettier

이 명령어들을 매번 정확하게 기억하는 것은 어렵기 때문에, 반복적으로 수행하는 동작에 대해 package.json에 스크립트로 등록해 두면 간단한 명령어로 편리하게 사용할 수 있다.

🗂️ 스크립트 등록 방법

Node.js 프로젝트의 package.json에 scripts 항목이 있는데, 해당 부분에서 직접 편집하거나 명령어를 입력하여 등록하는 방법이 있다.

1. package.json을 열고 직접 편집
2. npm pkg set scripts.{스크립트 이름}={명령어} 명령어 입력

$ npm pkg set scripts.hi "echo 'HI!'"

file : package.json

{
    // 생략
    "scripts": {
        "hi": "echo 'Hi!'"  
        "start": "react-scripts start"
    },
    // 생략
}

🧠 스크립트 실행 방법

스크립트 등록을 마치면 npm run <스크립트 이름> 명령어를 입력하여 실행할 수 있다.

$ npm run hi

> our-project@1.0.0 hi
> echo 'Hi!'

Hi!

npm start도 이 방식으로 동작하는 것이며, 단지 "start"만 예외적으로 run 생략이 가능하다.

🧩 보너스: 자주 쓰는 스크립트 예시

package.json 파일에 다음과 같이 등록해 두면 터미널에서 짧은 명령으로 실행할 수 있어 편리하다.

"scripts": {
  "start": "react-scripts start",
  "build": "react-scripts build",
  "test": "react-scripts test",
  "lint": "eslint .",
  "format": "prettier --write ."
}

$ npm start       # 개발 서버 실행
$ npm run build   # 빌드
$ npm run test    # 테스트
$ npm run lint    # 린트
$ npm run format  # 코드 포맷팅