Next.js package.json: scripts dependencies 이해

학습 목표·선수 지식: 프로젝트 명령과 인수 전달을 직접 실행합니다. 선수 지식: 터미널 폴더 이동.

실습 경로: 전체 코드. 먼저 설명에서 지정한 파일만 읽고, 설정·테스트 파일은 필요한 때 확인하세요.

Node.js·npm·package.json의 역할

브라우저 밖에서 JavaScript를 실행하는 런타임이 Node.js입니다. npm은 필요한 패키지를 설치하고 프로젝트에 정의된 명령을 실행합니다. package.json은 두 도구 자체가 아니라 프로젝트의 설정과 선언을 담은 JSON 파일입니다. 세 이름을 구분하면 다른 프레임워크에서도 같은 기준으로 프로젝트를 읽을 수 있습니다. package.json 전체 코드

처음 설치한다면 Node.js 공식 다운로드에서 LTS를 선택하세요. 새 터미널에서 아래 두 명령으로 설치를 확인합니다. 현재 프로젝트가 요구하는 Node.js 버전은 package.json의 engines, 저장소 안내와 프레임워크 문서를 함께 확인합니다. package.json 전체 코드

node --version
npm --version

scripts로 첫 명령 실행하기

새 실습 폴더를 만들고 아래 두 파일을 같은 폴더에 저장합니다. 이 예제에는 외부 패키지가 없으므로 npm install 없이 실행할 수 있습니다. scripts의 왼쪽은 명령 이름이고 오른쪽은 실제 실행할 명령입니다.

package.json

{
  "name": "package-reading-practice",
  "private": true,
  "scripts": {
    "hello": "node hello.mjs"
  }
}

console.log("실행 규칙을 확인했습니다.");

hello.mjs

두 파일이 있는 폴더에서 실행합니다. npm은 현재 프로젝트의 scripts.hello 값을 찾아 Node.js로 hello.mjs를 실행합니다. 설정에 없는 이름을 호출하면 Missing script 오류가 나므로 명령 이름부터 대조하세요. hello.mjs 전체 코드

npm run hello

npm이 보여주는 실행 안내 다음에 실행 규칙을 확인했습니다.가 출력되어야 합니다. npm run만 입력하면 정의된 스크립트 목록을 볼 수 있습니다. 스크립트는 프로젝트가 정한 규칙이므로 build·test 같은 이름이 모든 저장소에 자동으로 존재하는 것은 아닙니다.

dependencies와 잠금 파일 읽기

dependencies에는 애플리케이션이 사용하는 패키지를, devDependencies에는 개발·타입 검사·테스트 등의 도구를 기록하는 것이 일반적입니다. Next.js 앱의 next·react·react-dom은 전자, TypeScript와 린트 도구는 후자의 대표 예입니다. 다만 빌드를 수행하는 환경에는 개발 도구도 필요할 수 있습니다. 운영 설치라는 이유만으로 빌드 전에 devDependencies를 생략하면 필요한 컴파일러가 없어질 수 있습니다.

package.json은 허용하는 버전 범위를 선언하고 package-lock.json은 npm이 해석한 의존성 트리의 구체적인 버전과 무결성 정보를 기록합니다. node_modules는 실제 설치 결과입니다. 다른 사람이 같은 프로젝트를 받았을 때 잠금 파일까지 함께 받아야 재현성이 높아집니다. npm ci는 잠금 파일을 기준으로 설치하며 package.json과 맞지 않으면 실패합니다. 잠금 파일을 지우기 전에 어떤 변경으로 불일치가 생겼는지 확인하세요. package.json 전체 코드

브라우저 번들에 포함되는지는 dependencies라는 분류만으로 결정되지 않습니다. 어떤 모듈에서 import했는지와 빌드 과정이 함께 결정합니다. 서버 전용 코드를 클라이언트 컴포넌트에서 가져오는 문제는 별도로 점검해야 합니다. pnpm을 사용하는 저장소라면 pnpm 설치 오류와 lockfile·workspace 점검을 참고하세요.

Next.js의 개발·빌드·실행 구분

아래는 Next.js 프로젝트에서 읽게 되는 scripts 부분의 예시입니다. 전체 프로젝트를 생성하는 코드는 아니므로 앞의 작은 Node.js 실습 폴더에 그대로 덮어쓰지 마세요. Next.js 설치와 페이지 구성은 공식 설치 안내와 App Router 학습 로드맵에서 이어집니다.

{
  "scripts": {
    "dev": "next dev",
    "build": "next build",
    "start": "next start"
  }
}

dev가 켜졌다는 사실은 프로덕션 빌드 성공을 보장하지 않습니다. build가 산출물을 만들고 start는 그 결과를 서비스에 가까운 방식으로 실행합니다. build 산출물은 .next 폴더의 역할에서 더 살펴볼 수 있습니다.

프로젝트를 읽는 순서와 완료 기준

새 저장소를 열면 먼저 README와 Node.js 버전을 확인하고, package.json의 scripts를 읽고, 잠금 파일에 맞는 패키지 관리자를 고르세요. 다음으로 앱 진입점과 라우팅 구조를 확인합니다. App Router에서는 app/layout.tsx가 공통 골격, app/page.tsx가 홈 화면, app/products/page.tsx가 /products 화면을 담당합니다. package.json 전체 코드

기능 예제를 읽기 전 “어느 폴더에서 어떤 명령을 실행하고, 어떤 파일이 진입점인가”를 설명할 수 있어야 합니다. 이 글의 완료 기준은 hello 명령을 직접 실행하고, 실행 이름과 실제 명령의 관계를 설명하며, Next.js의 dev·build·start를 목적에 맞게 고르는 것입니다.

자주 막히는 지점

package.json을 찾지 못합니다. 터미널의 현재 폴더를 확인하고 프로젝트 루트로 이동하세요. JSON 문법 오류가 납니다. 키와 문자열의 큰따옴표, 쉼표와 중괄호를 확인합니다. JSON에는 주석이나 마지막 항목 뒤 쉼표를 넣지 않습니다. package.json 전체 코드

next 명령을 찾지 못합니다. Next.js 프로젝트의 의존성이 설치되었는지 확인하세요. npm run은 설치된 로컬 실행 파일을 찾아 호출합니다. 설치가 실패합니다. Node.js 요구 버전, 잠금 파일과 패키지 관리자, workspace 설정을 먼저 비교합니다.

세부 필드와 실행 순서는 npm package.json 문서와 npm scripts 문서에서 확인할 수 있습니다. package.json 전체 코드

npm 스크립트에 인수를 전달해 봅니다

프로젝트 루트 터미널 · 실행 명령

npm run hello -- --name=reader
npm run dev -- --port 3100

첫 명령은 hello.mjs에 –name=reader 인수를 전달하지만 기존 파일이 인수를 읽지 않아 출력 문구는 그대로입니다. 두 번째는 Next.js 프로젝트의 dev 스크립트가 next dev일 때 3100 포트로 실행합니다. — 앞은 npm, 뒤는 실행 대상 명령의 인수라는 차이를 설명할 수 있으면 명령 복사에서 한 단계 나아간 것입니다. hello.mjs 전체 코드

npm run typecheck나 npm test가 존재하는지도 scripts에서 확인하세요. Next.js 16의 next build는 별도 lint 실행을 대신하지 않습니다. CI에 lint가 필요하면 사용하는 ESLint 설정과 실행 스크립트를 따로 둡니다.

공식 기준과 확인 범위

확인일: 2026-09-12. API 설명은 Next.js 16 App Router 기준이며 과거 릴리스 글은 본문의 태그 범위를 유지합니다. 부분 API 코드는 기존 프로젝트에 통합하는 예시입니다.

• https://docs.npmjs.com/cli/v11/commands/npm-run-script
• https://nextjs.org/docs/app/guides/upgrading/version-16

공식 자료 재확인: 2026-09-12. 이 글의 실행하지 않은 브라우저/배포 점검은 독자 확인 과제로 구분합니다.