pnpm 사용법: 설치·기본 명령어·워크스페이스 설정

pnpm 설치와 기본 명령·workspace 설정에서 프로젝트 기준을 어떻게 확인하나요?

pnpm은 의존성 설치와 명령 실행을 관리하고 workspace로 여러 패키지를 연결할 수 있습니다. 프로젝트의 packageManager, workspace 설정, 잠금 파일을 함께 읽으세요.

적용 조건·범위: 이 글의 체크포인트는 Node.js 24.19.0과 pnpm 11.19.0을 기준으로 검증합니다. Node.js 24 계열이 준비된 환경에서는 다음 명령으로 예제와 같은 pnpm 버전을 설치할 수 있습니다.

본문 근거: pnpm.io · pnpm.io/workspaces

독립 실습: 작은 workspace 연결

새 빈 pnpm-practice 폴더에 네 파일을 경로대로 저장합니다. 이 예제는 외부 의존성 없이 workspace와 filter 연결을 확인합니다.

package.json 전체 코드

{
  "name": "pnpm-practice",
  "private": true,
  "packageManager": "pnpm@11.19.0",
  "scripts": {
    "hello": "pnpm --filter @practice/hello hello"
  }
}

pnpm-workspace.yaml 전체 코드

packages:
  - 'apps/*'

apps/hello/package.json 전체 코드

{
  "name": "@practice/hello",
  "private": true,
  "scripts": {
    "hello": "node hello.cjs"
  }
}

apps/hello/hello.cjs 전체 코드

console.log('workspace connected');

pnpm install
pnpm hello
pnpm install --frozen-lockfile

기대 결과: workspace connected가 출력되고 마지막 설치가 종료 코드 0이면 같은 lockfile을 다시 사용할 수 있습니다. 최초 install이 pnpm-lock.yaml을 생성합니다.

변형 과제: 하위 패키지의 name을 @practice/hello2로 바꿨을 때 기존 filter가 대상을 찾지 못하는 이유를 설명하고 루트 script도 같은 이름으로 고칩니다.

왜 pnpm을 기준으로 사용하는가

npm, pnpm, Yarn은 모두 JavaScript 프로젝트의 의존성을 설치하고 package.json의 script를 실행할 수 있습니다.

TaskFlow에서는 pnpm을 기준으로 사용합니다.

패키지 저장 공간을 효율적으로 사용
workspace 지원
하나의 lockfile로 여러 workspace 관리
선언하지 않은 의존성 접근을 비교적 엄격하게 제한

다만 “pnpm이 무조건 더 좋은 도구”라는 의미는 아닙니다. 프로젝트가 이미 npm이나 Yarn으로 안정적으로 운영 중이라면 패키지 매니저를 바꾸는 비용도 고려해야 합니다. 중요한 것은 한 저장소 안에서 기준을 하나로 통일하는 것입니다.

설치 전 확인

먼저 Node.js와 npm을 확인합니다.

node -v
npm -v

이 글의 체크포인트는 Node.js 24.19.0과 pnpm 11.19.0을 기준으로 검증합니다. Node.js 24 계열이 준비된 환경에서는 다음 명령으로 예제와 같은 pnpm 버전을 설치할 수 있습니다.

npm install -g pnpm@11.19.0
pnpm --version

기존 저장소를 다룰 때는 해당 저장소의 packageManager 기준을 먼저 확인합니다. 설치 권한이나 PATH가 다른 환경은 pnpm 공식 설치 문서를 참고합니다.

설치가 끝났다면 버전을 확인합니다.

pnpm -v

명령이 인식되지 않는다면 패키지를 다시 설치하기 전에 터미널을 새로 열고 PATH가 반영됐는지 확인합니다.

pnpm-lock.yaml은 왜 필요한가

package.json에는 보통 허용 가능한 버전 범위가 들어갑니다.

{
  "dependencies": {
    "react": "^19.0.0"
  }
}

package.json만으로는 설치 시점에 따라 하위 의존성 조합이 달라질 수 있습니다. pnpm-lock.yaml은 실제로 해석된 의존성 버전과 관계를 기록합니다.

package.json
→ 어떤 패키지와 버전 범위를 원하는가

pnpm-lock.yaml
→ 실제로 어떤 버전 조합이 설치됐는가

팀 프로젝트에서는 lockfile을 저장소에 포함해 설치 결과를 재현할 수 있게 합니다.

여러 lockfile을 동시에 만들지 않기

TaskFlow 루트에 다음 파일을 함께 두지 않습니다.

package-lock.json
yarn.lock
pnpm-lock.yaml

패키지 매니저가 섞이면 같은 package.json을 기준으로 서로 다른 설치 결과가 생길 수 있습니다. TaskFlow 기준은 pnpm이므로 메인 루트에는 pnpm-lock.yaml만 유지합니다.

자주 발생하는 문제

pnpm 명령을 찾을 수 없습니다

pnpm -v

설치 직후라면 터미널을 새로 열어 PATH 반영 여부를 확인합니다.

잘못된 폴더에서 pnpm install을 실행했습니다

Windows PowerShell:

Get-Location

macOS/Linux:

pwd

workspace 루트와 개별 앱 폴더를 혼동하면 다른 package.json을 기준으로 설치할 수 있습니다.

package-lock.json이 새로 생겼습니다

npm install을 실행했을 가능성이 있습니다. 원인을 확인한 뒤 잘못 생성한 npm 설치 결과를 정리하고 pnpm 기준으로 복구합니다.

node_modules부터 삭제하면 되나요

첫 해결책으로 사용하지 않습니다.

현재 폴더
packageManager
pnpm 버전
package.json
pnpm-workspace.yaml
pnpm-lock.yaml 변경 여부

7회차에서 pnpm install 오류를 이 순서대로 더 자세히 진단합니다.

학습 완료 체크리스트

npm과 pnpm의 역할을 구분할 수 있습니다.
pnpm 버전을 확인할 수 있습니다.
pnpm install, add, remove, dev 명령을 사용할 수 있습니다.
packageManager 필드가 필요한 이유를 설명할 수 있습니다.
pnpm-lock.yaml의 역할을 설명할 수 있습니다.
pnpm-workspace.yaml로 apps와 labs를 분리할 수 있습니다.
TaskFlow 루트에서 여러 패키지 매니저를 섞지 않는 기준을 이해했습니다.

선택 실습: 같은 프로젝트로 연습하기

TaskFlow는 작업을 관리하는 예제 앱입니다. 이 선택 실습에서는 앱을 실행·개발하는 환경과 설정을 준비합니다.

이번 글에서는 TaskFlow 개발환경 과정의 기준 패키지 매니저를 pnpm으로 정하고, 설치 확인부터 package.json script, lockfile, workspace까지 한 번에 정리합니다.

선택: 연재 프로젝트와 전체 자료

연재 프로젝트를 이어 만드는 분을 위한 자료입니다. 이 글의 개념과 예제만 찾으셨다면 필요한 파일과 실행 방법만 펼쳐보세요.

TaskFlow 프로젝트 적용

시작 체크포인트: 첫 회차입니다. 아래 전체 파일 또는 완료 ZIP을 새 폴더에 준비하고 시작합니다. 메인 앱은 루트에서 실행하고, labs는 해당 폴더의 package.json과 잠금 파일을 기준으로 따로 실행합니다.

이번 글에서는 TaskFlow 개발환경 과정의 기준 패키지 매니저를 pnpm으로 정하고, 설치 확인부터 package.json script, lockfile, workspace까지 한 번에 정리합니다. 목표는 “내 컴퓨터에서는 된다”가 아니라 새 폴더에서도 같은 명령으로 설치하고 실행할 수 있는 상태입니다.

터미널에서 현재 폴더를 이동하고 Node.js와 npm 버전을 확인할 수 있으면 충분합니다.

node -v
npm -v

Node.js 자체 설치와 PATH 문제를 처음부터 다루는 글은 아닙니다. 위 명령이 실행되지 않는다면 먼저 Node.js 설치와 터미널 PATH 상태를 확인해야 합니다.

TaskFlow 프로젝트 구조

이번 과정에서는 메인 앱과 오류 재현용 실습을 분리합니다.

taskflow/
├─ package.json
├─ pnpm-lock.yaml
├─ pnpm-workspace.yaml
├─ apps/
│  └─ web/
└─ labs/

나중에 labs 아래에 npm 충돌, Tailwind 경고, Storybook 오류를 재현하는 작은 프로젝트를 둘 수 있습니다. 오류 실습 때문에 메인 TaskFlow 의존성을 오염시키지 않는 것이 목적입니다.

전체 파일·코드 보기

package.json에서 확인할 것

루트 package.json의 핵심은 scripts와 packageManager입니다.

{
  "name": "taskflow",
  "private": true,
  "packageManager": "pnpm@11.19.0",
  "engines": {
    "node": ">=24"
  },
  "scripts": {
    "dev": "pnpm --filter @taskflow/web dev",
    "build": "pnpm --filter @taskflow/web build"
  }
}

packageManager에는 이 체크포인트의 검증 기준인 pnpm 11.19.0을 기록합니다. 특정 숫자를 외우는 것이 아니라 프로젝트가 어떤 패키지 매니저와 버전을 기준으로 설치됐는지 저장소 안에 남기는 것이 핵심입니다.

pnpm-workspace.yaml 만들기

packages:
  - "apps/*"

메인 workspace에는 apps 아래의 앱만 포함합니다. labs의 npm·Yarn·Tailwind·Storybook 실습은 각 폴더의 package.json과 lockfile로 독립 관리하며, 메인 pnpm 설치 대상에 포함하지 않습니다.

apps/web
labs/npm-eresolve
labs/tailwind-at-rule
labs/storybook-vite

실습 프로젝트 전체 코드

아래는 이번 회차 완료 시점의 전체 소스입니다. 파일 경로는 압축을 푼 체크포인트 폴더를 기준으로 합니다. 자동 생성되는 lockfile은 ZIP에 포함하며, node_modules·빌드 결과·실제 비밀값은 포함하지 않습니다. 메인 앱과 각 lab은 별도의 설치 범위를 유지합니다.

`.gitignore`

node_modules/
dist/
storybook-static/
.env.local
.env.*.local

`apps/web/index.html`

<!doctype html>
<html lang="ko">
<head><meta charset="UTF-8"><meta name="viewport" content="width=device-width, initial-scale=1.0"><title>TaskFlow 개발환경</title></head>
<body><main id="app"></main><script type="module" src="/src/main.js"></script></body>
</html>

`apps/web/package.json`

{
  "name": "@taskflow/web",
  "private": true,
  "type": "module",
  "scripts": {
    "dev": "vite --host 127.0.0.1",
    "build": "vite build"
  },
  "devDependencies": {
    "vite": "8.3.0"
  }
}

`apps/web/src/main.js`

import './style.css';

const app = document.querySelector('#app');
const title = document.createElement('h1');
title.textContent = 'TaskFlow';
const status = document.createElement('p');
status.textContent = '개발환경 스타터가 실행 중입니다.';
app.append(title, status);

`apps/web/src/style.css`

body { margin: 0; color: #202020; background: #f6f6f6; font: 16px/1.6 system-ui, sans-serif; }
main { max-width: 720px; margin: 64px auto; padding: 24px; }
h1 { font-size: 30px; font-weight: 500; }
p { overflow-wrap: anywhere; }

`docs/development-environment.md`

# TaskFlow 개발환경

이 스타터는 개발환경 진단을 위한 최소 Vite/vanilla JavaScript 앱입니다. 할 일 관리 기능이나 API 서버는 포함하지 않습니다.

Node.js 24.19.0, pnpm 11.19.0으로 검증했습니다. 루트는 pnpm만 사용하며 apps/*만 workspace입니다. labs의 npm/Yarn/pnpm 실습은 독립 프로젝트입니다.

`package.json`

{
  "name": "taskflow",
  "private": true,
  "packageManager": "pnpm@11.19.0",
  "engines": {
    "node": ">=24"
  },
  "scripts": {
    "dev": "pnpm --filter @taskflow/web dev",
    "build": "pnpm --filter @taskflow/web build"
  }
}

`pnpm-workspace.yaml`

packages:
  - "apps/*"

`README.md`

# TaskFlow 개발환경 01 완료 체크포인트

Node.js 24.19.0 / pnpm 11.19.0 검증 기준입니다. pnpm을 별도로 설치한 환경에서 실행하세요. ZIP에는 node_modules, dist, 로컬 환경 변수, 실제 비밀값이 없습니다.

1. 이 폴더에서 `pnpm install --frozen-lockfile`
2. `pnpm dev` 후 http://127.0.0.1:5173 확인
3. `pnpm build`

ESLint는 5회차부터 추가되므로 이 체크포인트에는 lint 명령이 없습니다.

apps/web가 Vite 루트입니다. 환경 변수도 이 폴더에 둡니다. 표시용 API 주소에 실제 요청을 보내지 않습니다. labs는 메인 workspace에서 제외되어 각 폴더에서 별도 설치합니다.

원문 단계별 전체 파일과 실행 검증 범위는 docs/development-environment.md를 확인하세요.

기본 명령어

의존성을 설치합니다.

pnpm install

패키지를 추가합니다.

pnpm --filter @taskflow/web add axios

개발 의존성으로 추가합니다.

pnpm --filter @taskflow/web add -D eslint

패키지를 제거합니다.

pnpm --filter @taskflow/web remove axios

script를 실행합니다. pnpm lint는 5회차에서 lint script와 ESLint를 추가한 뒤 실행합니다.

pnpm dev
pnpm lint

특정 workspace만 실행할 수도 있습니다.

pnpm --filter @taskflow/web dev

이 글을 읽고 바로 확인할 것

독자 질문: 처음 받은 프론트엔드 프로젝트에서 pnpm 설치·실행 기준을 어떻게 확인하나요?

얻을 결과: 저장소 루트에서 workspace 범위와 packageManager를 읽고, 잠금 파일을 유지한 설치 → 개발 서버 → 빌드 확인 경로를 설명할 수 있습니다.

직접 따라 할 순서

package.json의 packageManager와 scripts, 루트의 pnpm-workspace.yaml을 먼저 확인합니다.
기존 pnpm-lock.yaml을 유지한 채 루트에서 pnpm install --frozen-lockfile을 실행합니다.
pnpm dev로 앱 응답을 확인하고 별도 터미널에서 pnpm build를 실행합니다.

확인 결과 기준: 설치 실패 없이 종료되고 앱 페이지가 열리며 빌드가 성공하면 통과입니다. lint는 이 과정 5회차에서 도입합니다.

편집 검증 범위: 이번 보강에서 위 명령과 화면은 다시 실행하지 않았습니다(미확인). 본문 아래의 기존 실행 검증표는 이전 작업에서 기록한 결과이며, 독자는 자신의 환경에서 위 기준으로 확인해 주세요.

다음 학습: Yarn 사용법: Corepack 설치와 Classic·Modern 차이

이전 체크포인트

없음

현재 상태

패키지 매니저 기준 불명확
오류 재현 실습 위치 없음
환경 변수 계약 없음
lint 검증 기준 미정

이번 변경

pnpm을 TaskFlow 기준 패키지 매니저로 확정
packageManager 명시
pnpm workspace 준비
apps와 labs 역할 분리
install / dev 기본 명령 확정

변경 파일

package.json
pnpm-workspace.yaml
pnpm-lock.yaml

실행 확인

pnpm install
pnpm dev

lint script가 이미 있다면 다음 명령도 확인합니다.

pnpm lint

5회차에서 ESLint를 연결한 뒤 lint를 필수 검증으로 전환합니다.

완료 체크포인트

dev-env-step-01-pnpm-base

실행 검증 결과

검증 환경: Windows · Node.js 24.19.0 · pnpm 11.19.0 · Vite 8.3.0.

항목	확인 결과
새 작업 폴더의 pnpm install	성공
pnpm install `--frozen-lockfile`	성공
pnpm build	성공
pnpm dev	개발 서버 응답 HTTP 200 확인
pnpm lint	5회차에서 추가 예정 · 이 체크포인트에는 없음

개발 서버의 HTTP 응답을 확인했으며, 운영 배포와 모든 브라우저 조합을 검증한 것은 아닙니다.

다음 학습

다음 글에서는 TaskFlow 메인 패키지 매니저를 바꾸지 않고, 다른 저장소에서 Yarn을 만났을 때 Classic과 Modern을 구분하고 packageManager와 Corepack의 역할을 학습합니다.

다음 글: Yarn 사용법: Corepack 설치와 Classic·Modern 차이

공식 문서

pnpm: https://pnpm.io/
pnpm workspace: https://pnpm.io/workspaces

체크포인트 다운로드

dev-env-step-01-pnpm-base 완료 ZIP 다운로드

글 소개·학습 준비·전체 목차

개발환경 · 1 / 11 · 필수 학습 · pnpm 사용법

프론트엔드 프로젝트를 다른 PC에서 다시 실행할 때 가장 먼저 깨지는 지점은 코드보다 개발환경인 경우가 많습니다.

이번 글에서 배우는 내용

npm과 pnpm의 역할 차이
pnpm 설치와 버전 확인
package.json의 scripts와 packageManager
pnpm-lock.yaml이 필요한 이유
pnpm-workspace.yaml의 역할
pnpm install, add, remove, run 사용법
새 환경에서 install → dev → lint 재현
TaskFlow 개발환경의 패키지 매니저 기준 확정

선수 지식

Node.js 24와 터미널 이동 방법을 알고 시작합니다. pnpm 준비는 이 글의 설치 전 확인 절을 따릅니다.

왜 pnpm을 기준으로 사용하는가
설치 전 확인
pnpm-lock.yaml은 왜 필요한가
여러 lockfile을 동시에 만들지 않기
자주 발생하는 문제
학습 완료 체크리스트
독립 실습: 작은 workspace 연결
TaskFlow 프로젝트 적용
TaskFlow 프로젝트 구조
package.json에서 확인할 것
pnpm-workspace.yaml 만들기
기본 명령어
이 글을 읽고 바로 확인할 것
실습 프로젝트 전체 코드
실행 검증 결과
다음 학습
공식 문서

이 글이 도움이 되었나요?

조회 중

읽음 기록

읽음 — / 전체 11개 · 필수 6개

이 글을 쓴 해비

웹사이트를 제작·운영하고, 개인 서비스와 자동화·AI 도구를 만듭니다. 직접 만들며 배운 내용과 문제 해결 과정을 BlogFlow에 기록합니다.

새 글 받아보기

RSS 리더에서 BlogFlow의 새 글을 확인할 수 있습니다.

RSS 피드 구독하기