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

• Yarn이란 무엇인가
• Yarn 설치와 버전 확인
• 프로젝트 시작과 의존성 설치
• 패키지 추가와 삭제
• 스크립트 실행과 자주 쓰는 명령어
• yarn.lock 파일 이해하기
• 초보자가 자주 헷갈리는 부분
• 핵심 명령어 체크리스트
• Yarn Classic과 Modern 차이
• 공식 문서

Yarn이란 무엇인가

목표는 Yarn Classic 1.x와 Modern의 설정·설치 방식을 구분하고 저장소가 고정한 버전으로 스크립트를 실행하는 것입니다. Node.js와 package.json 기본 구조를 알고 시작합니다. 새 학습 프로젝트와 기존 팀 저장소의 명령을 분리하여 버전 변경을 실수로 섞지 않습니다.

패키지 매니저의 역할은 단순히 파일을 내려받는 것에서 끝나지 않습니다. 어떤 패키지가 필요한지 package.json에 기록하고, 실제 설치된 버전 조합을 yarn.lock에 고정하며, Classic이나 nodeLinker: node-modules 설정에서는 패키지를 node_modules에 배치합니다. Modern Yarn의 기본 PnP 방식에서는 .pnp.cjs 로더로 패키지 위치를 연결합니다. 그래서 팀원이 같은 프로젝트를 받아도 비슷한 환경에서 실행할 수 있습니다.

npm도 같은 역할을 하는 패키지 매니저입니다. Yarn은 npm의 대체 선택지로 자주 쓰이며, 명령어 이름과 동작 방식이 조금 다릅니다. 초보자 입장에서는 둘 중 무엇이 더 좋은지를 먼저 따지기보다, 현재 프로젝트가 어떤 도구를 기준으로 관리되는지 확인하는 것이 더 중요합니다.

Yarn 설치와 버전 확인

Yarn을 쓰기 전에 터미널에서 설치 여부를 확인합니다. 이미 설치되어 있다면 버전 번호가 출력됩니다.

yarn --version

최근 Yarn은 프로젝트별 버전 관리를 권장합니다. 먼저 Corepack을 설치한 뒤 새 프로젝트를 Modern Yarn으로 초기화할 수 있습니다. 기존 저장소에서는 packageManager와 yarn.lock을 확인해 팀이 고정한 버전을 그대로 사용하세요.

npm install -g corepack
corepack enable
yarn --version

프로젝트마다 요구하는 Yarn 버전이 다를 수 있습니다. 특히 Yarn Classic과 최신 계열의 Yarn Berry는 설정 파일, 설치 전략, PnP 사용 여부가 다를 수 있습니다. 이 글은 입문자가 자주 만나는 기본 명령 흐름에 초점을 맞추므로, 처음에는 현재 컴퓨터의 전역 설정만 보지 말고 프로젝트 폴더 안의 package.json, yarn.lock, .yarnrc.yml 같은 파일을 함께 확인하는 습관이 좋습니다.

• package.json: 프로젝트 이름, 스크립트, 의존성 목록이 들어 있습니다.
• yarn.lock: 설치된 패키지 버전 조합을 고정합니다.
• node_modules: Classic 또는 node-modules 설치 방식의 패키지 폴더입니다. Modern의 기본 PnP 방식에서는 이 폴더 대신 .pnp.cjs를 확인합니다.
• .yarnrc.yml: Yarn 동작 방식을 설정하는 파일입니다.

설치는 패키지를 준비하고 run은 내 프로그램을 실행합니다

Corepack이 이미 있는 환경이라도 shim 활성화가 안 되어 있으면 yarn 명령을 찾지 못할 수 있습니다. corepack --version과 corepack enable을 구분하세요. 권한 오류가 나면 시스템 폴더를 임의 삭제하지 말고 사용 중인 Node 설치 관리자와 설치 위치를 확인합니다.

새 빈 yarn-lab 폴더에서만 yarn init -2를 실행합니다. 생성된 package.json의 packageManager 값은 유지하고 scripts에 아래 항목을 추가합니다. 이것은 package.json 전체가 아닌 추가할 속성입니다.

package.json — scripts 속성 부분 코드

{
  "scripts": {
    "hello": "node hello.mjs"
  }
}

hello.mjs — 전체 파일

const message = "Yarn script is ready";
console.log(message);

터미널에서 실행할 명령

yarn install
yarn run hello
yarn install --immutable

hello는 정확히 Yarn script is ready를 출력해야 합니다. 마지막 명령은 잠금 파일을 바꾸지 않고 설치할 수 있는지 확인하며, 처음 설치하기 전에 실행하면 필요한 lockfile이 없어 실패할 수 있습니다. Modern에서 설치 결과가 .pnp.cjs로 나타나도 설치 실패가 아닙니다. node_modules가 꼭 필요한 도구라면 아래 프로젝트 설정을 선택한 뒤 다시 install합니다.

.yarnrc.yml — 다른 설정이 없다면 전체 파일

nodeLinker: node-modules

PnP를 쓰는 저장소에 이 설정을 무조건 추가하지 않습니다. linker 전환은 팀의 도구 호환성을 확인하고 lockfile·설정 변경을 검토할 작업입니다. Classic의 frozen-lockfile과 Modern의 immutable을 같은 옵션처럼 복사하지 마세요. 기존 저장소를 받았을 때는 init이나 set version stable 대신 고정된 packageManager를 따르고 install합니다.

프로젝트 시작과 의존성 설치

새 프로젝트를 직접 만들 때는 먼저 폴더를 만들고 yarn init으로 package.json을 생성할 수 있습니다. 학습용으로 간단히 시작한다면 다음 흐름이면 충분합니다.

mkdir my-app
cd my-app
yarn init -2

yarn init -2는 새 프로젝트를 Modern Yarn으로 초기화합니다. Classic 1.x를 유지하는 프로젝트에서는 yarn init -y로 기본값의 package.json을 생성할 수 있습니다. 이후 필요한 패키지를 추가하면 dependencies 또는 devDependencies에 항목이 기록됩니다.

반대로 이미 만들어진 프로젝트를 내려받았다면 가장 먼저 할 일은 보통 yarn install입니다. 저장소에는 node_modules가 포함되지 않는 경우가 많기 때문에, 프로젝트 실행 전에 필요한 패키지를 다시 설치해야 합니다.

git clone example-project
cd example-project
yarn install

yarn install은 package.json과 yarn.lock을 기준으로 필요한 패키지를 설치합니다. 이 명령어는 새 라이브러리를 추가하는 명령이 아니라, 이미 정의된 의존성을 현재 컴퓨터에 맞게 내려받는 명령입니다. 기존 프로젝트를 처음 실행할 때는 거의 항상 의존성 설치부터 확인해야 합니다.

패키지 추가와 삭제

실제 개발 중에는 새로운 기능을 만들기 위해 패키지를 추가하는 일이 많습니다. 예를 들어 React 프로젝트에서 HTTP 요청을 보내기 위해 axios를 추가한다면 yarn add를 사용합니다.

yarn add axios

이 명령은 axios를 설치하고 package.json의 dependencies에 기록합니다. dependencies는 애플리케이션이 실제 실행될 때 필요한 패키지 목록입니다.

반면 코드 포맷터, 테스트 도구, 빌드 보조 도구처럼 개발 과정에서만 필요한 패키지는 devDependencies에 넣는 것이 일반적입니다. 이때는 -D 옵션을 붙입니다.

yarn add -D prettier

-D는 --dev의 축약 형태입니다. 예를 들어 prettier, eslint, vitest 같은 도구는 서비스 실행 자체보다 개발과 검증 과정에 가까우므로 devDependencies에 두는 경우가 많습니다.

더 이상 필요 없는 패키지는 yarn remove로 제거합니다.

yarn remove axios

yarn remove는 설치된 패키지를 지우고 package.json과 yarn.lock의 관련 정보도 함께 갱신합니다. 단순히 node_modules 폴더에서 직접 삭제하는 방식은 피하는 것이 좋습니다. 패키지 매니저가 관리하는 기록과 실제 파일 상태가 어긋날 수 있기 때문입니다.

스크립트 실행과 자주 쓰는 명령어

package.json에는 scripts라는 영역이 자주 들어 있습니다. 이곳에는 개발 서버 실행, 빌드, 테스트, 린트 같은 반복 명령이 짧은 이름으로 정의됩니다.

{
  "scripts": {
    "dev": "vite",
    "build": "vite build",
    "test": "vitest",
    "lint": "eslint ."
  }
}

위와 같은 설정이 있다면 yarn run dev로 개발 서버를 실행할 수 있습니다.

yarn run dev

Yarn에서는 많은 경우 run을 생략해 yarn dev처럼 실행할 수도 있습니다. 그래서 실무에서는 다음 두 명령을 같은 의미로 보는 경우가 많습니다.

yarn run build
yarn build

다만 처음 배우는 단계에서는 package.json의 scripts를 먼저 열어 보고, 실제로 어떤 명령이 연결되어 있는지 확인하는 습관이 중요합니다. yarn dev가 항상 개발 서버를 의미하는 것은 아닙니다. 프로젝트 작성자가 scripts에 어떻게 정의했는지에 따라 동작이 달라집니다.

• yarn install: 프로젝트 의존성을 설치합니다.
• yarn add package-name: 실행에 필요한 패키지를 추가합니다.
• yarn add -D package-name: 개발용 패키지를 추가합니다.
• yarn remove package-name: 패키지를 제거합니다.
• yarn run script-name: package.json의 scripts를 실행합니다.

yarn.lock 파일 이해하기

yarn.lock은 초보자가 처음 보면 직접 수정해야 할 설정 파일처럼 느껴질 수 있습니다. 하지만 보통은 사람이 손으로 편집하는 파일이 아닙니다. yarn install, yarn add, yarn remove 같은 명령을 실행하면 Yarn이 자동으로 갱신합니다.

이 파일이 필요한 이유는 패키지 버전 조합을 안정적으로 유지하기 위해서입니다. package.json에는 ^1.2.3처럼 일정 범위의 버전을 허용하는 표기가 들어갈 수 있습니다. 이때 yarn.lock은 실제로 어떤 버전이 설치되었는지 더 구체적으로 기록합니다.

팀 프로젝트에서는 yarn.lock을 저장소에 함께 커밋하는 것이 일반적입니다. 그래야 다른 개발자와 배포 환경이 같은 의존성 조합을 사용할 가능성이 높아집니다. yarn.lock을 이유 없이 삭제하거나 무시하면 환경마다 다른 문제가 생길 수 있습니다.

패키지를 추가하거나 제거한 뒤 package.json과 yarn.lock이 함께 변경되는 것은 자연스러운 일입니다. 코드 변경 없이 lock 파일만 바뀌었다면 어떤 명령을 실행했는지, 패키지 버전이 의도대로 바뀐 것인지 확인하면 됩니다.

초보자가 자주 헷갈리는 부분

첫 번째로 많이 헷갈리는 부분은 yarn install과 yarn add의 차이입니다. yarn install은 이미 적혀 있는 의존성을 설치하는 명령이고, yarn add는 새로운 패키지를 프로젝트에 등록하는 명령입니다.

두 번째는 dependencies와 devDependencies의 차이입니다. 애플리케이션 실행에 필요한 패키지는 dependencies, 개발 중에만 필요한 도구는 devDependencies에 두는 식으로 이해하면 출발점으로 충분합니다.

세 번째는 npm 명령어와 Yarn 명령어를 섞어 쓰는 문제입니다. 같은 프로젝트에서 package-lock.json과 yarn.lock이 동시에 생기면 어떤 패키지 매니저를 기준으로 해야 하는지 혼란스러워질 수 있습니다. 프로젝트가 Yarn을 기준으로 한다면 보통 yarn.lock을 기준으로 작업합니다.

• npm install에 가까운 명령은 yarn install입니다.
• npm install axios에 가까운 명령은 yarn add axios입니다.
• npm install -D eslint에 가까운 명령은 yarn add -D eslint입니다.
• npm run dev에 가까운 명령은 yarn run dev 또는 yarn dev입니다.

핵심 명령어 체크리스트

Yarn을 처음 배울 때 모든 옵션을 한 번에 외울 필요는 없습니다. 실제 프로젝트를 실행하고 수정하는 데 필요한 명령부터 익히면 됩니다. 특히 기존 프로젝트를 받은 직후, 새 라이브러리를 추가할 때, 개발 서버를 실행할 때의 흐름을 먼저 몸에 익히는 것이 좋습니다.

yarn --version
yarn install
yarn add axios
yarn add -D prettier
yarn remove axios
yarn dev
yarn build

정리하면 Yarn은 Node.js 프로젝트의 의존성을 설치하고 관리하며, package.json에 정의된 작업을 실행하는 도구입니다. 초보자에게 가장 중요한 기준은 명령어를 외우는 것보다 현재 상황을 구분하는 것입니다. 프로젝트를 처음 받았다면 yarn install, 패키지를 새로 넣는다면 yarn add, 개발용 도구라면 yarn add -D, 실행 명령은 package.json의 scripts에서 확인하면 됩니다.

Yarn Classic과 Modern 차이

구분	Yarn Classic	Yarn Modern
대표 버전	1.x	2.x 이상
버전 관리	전역 설치가 흔함	프로젝트별 버전 고정 권장
설치 방식	node_modules 중심	node_modules 또는 Plug’n’Play 선택

기존 프로젝트의 Yarn 버전을 임의로 올리면 잠금 파일과 설치 방식이 달라질 수 있습니다. package.json의 packageManager, 저장소의 .yarnrc.yml, yarn.lock을 먼저 확인하는 것이 안전합니다.

공식 문서

• Yarn 설치 공식 가이드
• Yarn Modern 마이그레이션 가이드