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

Yarn Classic과 Modern

보통 Yarn Classic은 Yarn 1 계열을 의미하고, Modern은 이후 세대의 Yarn을 의미합니다.

오래된 프로젝트를 열었을 때 package.json, yarn.lock, .yarnrc 또는 .yarnrc.yml 구조를 보면 프로젝트 세대와 설정 방식을 추정할 수 있습니다.

중요한 것은 “Yarn이면 모두 같은 방식”이라고 생각하지 않는 것입니다. 오래된 블로그 글의 전역 설치 명령을 그대로 실행하기 전에 저장소가 어떤 Yarn 버전을 전제로 하는지 먼저 확인해야 합니다.

packageManager부터 확인하기

프로젝트 루트의 package.json을 확인합니다.

{
  "name": "sample-project",
  "packageManager": "yarn@4.18.0"
}

위 버전은 이 글의 독립 lab에서 사용하는 예제입니다. 기존 저장소에서는 해당 프로젝트가 지정한 버전을 유지합니다. packageManager가 있다면 기대하는 패키지 매니저와 버전을 확인할 수 있습니다.

Yarn 공식 문서도 이 필드가 프로젝트별 Yarn 버전을 식별하는 역할을 한다고 설명합니다.

Corepack이 하는 일

Corepack은 프로젝트가 요구하는 패키지 매니저 버전을 연결하는 도구입니다.

package.json
packageManager: yarn@...
        ↓
Corepack
        ↓
프로젝트가 요구하는 Yarn 실행

중요한 점은 Corepack 설치 방식이 Node.js 배포 정책에 따라 달라질 수 있다는 것입니다.

현재 Yarn 공식 설치 안내는 Corepack을 별도로 설치한 뒤 프로젝트별 Yarn 버전을 구성하는 흐름을 안내합니다. 따라서 “Node.js를 설치하면 Corepack이 항상 포함된다”라고 단정하지 않습니다.

현재 설치 여부 확인

yarn --version
corepack --version

Corepack이 없다면 현재 Yarn 공식 설치 문서의 지침을 확인합니다.

공식 설치 안내의 대표 흐름은 다음과 같습니다.

npm install -g corepack
corepack enable yarn

설치 방법은 발행 시점 공식 문서를 다시 확인합니다.

새 Yarn 프로젝트 실습

TaskFlow 메인 프로젝트가 아니라 별도 임시 폴더에서 실습합니다.

labs/
└─ yarn-modern/

Yarn 프로젝트를 초기화합니다.

yarn init -2

Yarn 버전을 프로젝트에 설정할 때는 다음과 같은 명령을 사용할 수 있습니다.

yarn set version stable

설정 후 package.json의 packageManager 값을 확인합니다.

yarn.lock의 역할

package.json
→ 원하는 의존성 범위

yarn.lock
→ Yarn이 해석한 실제 의존성 조합

TaskFlow 메인 프로젝트는 pnpm을 사용하므로 루트에 yarn.lock을 만들지 않습니다.

Yarn 실습은 labs/yarn-modern처럼 별도 프로젝트에서만 진행합니다.

yarn install과 script 실행

yarn install

기존 저장소에 dev와 lint script가 정의돼 있다면 각각 yarn dev와 yarn lint를 실행할 수 있습니다. yarn init -2만 실행한 빈 프로젝트에는 이 script가 자동으로 생기지 않습니다.

명령 이름은 npm이나 pnpm과 비슷해 보여도 설치 전략과 프로젝트 설정은 다를 수 있습니다.

Modern Yarn에서는 .yarnrc.yml, Plug’n’Play, nodeLinker 같은 설정을 사용하는 프로젝트도 있으므로 기존 저장소의 설정을 먼저 읽어야 합니다.

Yarn 프로젝트를 받았을 때 확인 순서

1. package.json의 packageManager
2. yarn.lock 존재 여부
3. .yarnrc.yml 존재 여부
4. .yarn/ 디렉터리 구성
5. README의 설치 명령
6. Corepack 상태
7. yarn install

처음부터 최신 Yarn으로 덮어쓰면 기존 저장소가 기대하는 설치 결과와 달라질 수 있습니다.

Classic 프로젝트에서 주의할 점

다음과 같은 상황이라면 저장소 기준부터 확인합니다.

packageManager 없음
오래된 yarn.lock
.yarnrc 사용
README에 Yarn 1 명시
CI에서 특정 Yarn 버전 설치

“Classic이 오래됐으니 바로 Modern으로 올린다”가 해결책은 아닙니다. 버전 업그레이드는 별도 마이그레이션 작업입니다.

자주 발생하는 오류

yarn 명령이 실행되지 않습니다

yarn --version
corepack --version

Yarn 자체가 없는 문제와 Corepack이 없는 문제를 구분합니다.

전역 Yarn과 프로젝트 Yarn 버전이 다릅니다

package.json의 packageManager를 먼저 확인합니다. 프로젝트가 버전을 고정하고 있다면 전역 최신 버전보다 프로젝트 기준이 우선입니다.

pnpm 프로젝트에서 yarn install을 실행했습니다

TaskFlow 루트에서는 실행하지 않습니다. 새 yarn.lock이 생겼다면 어떤 명령으로 생성됐는지 확인하고 메인 프로젝트의 패키지 매니저 기준을 복구합니다.

Corepack은 항상 Node.js에 포함되어 있나요

그렇게 단정하지 않습니다. Node.js 버전과 설치 경로에 따라 제공 상태가 달라질 수 있으므로 Yarn 공식 설치 문서를 확인합니다.

학습 완료 체크리스트

• Yarn Classic과 Modern을 구분할 수 있습니다.
• packageManager에서 Yarn 버전을 확인할 수 있습니다.
• Corepack의 역할을 설명할 수 있습니다.
• yarn과 corepack 명령 상태를 확인할 수 있습니다.
• yarn.lock의 역할을 설명할 수 있습니다.
• 기존 Yarn 프로젝트의 설정을 먼저 읽어야 하는 이유를 이해했습니다.
• TaskFlow 루트에서 pnpm과 Yarn을 섞지 않습니다.

독립 실습: Yarn script 실행

기존 앱 밖의 새 연습 폴더에 아래 파일을 그대로 저장합니다. 표시한 경로는 이 연습 폴더 기준입니다. 하단 완료 ZIP을 사용할 경우 labs/yarn-modern/ 폴더만 별도로 열어도 됩니다. 이전 TaskFlow 앱 파일은 필요하지 않습니다.

.yarnrc.yml 전체 코드

nodeLinker: node-modules

package.json 전체 코드

{
  "name": "taskflow-yarn-lab",
  "private": true,
  "type": "module",
  "packageManager": "yarn@4.18.0",
  "scripts": {
    "dev": "node src/main.js",
    "lint": "node --check src/main.js"
  }
}

src/main.js 전체 코드

console.log('TaskFlow Yarn 독립 실습');

yarn --version
yarn install
yarn dev
yarn lint

기대 결과: dev에서 TaskFlow Yarn 독립 실습이 출력되고 lint가 종료 코드 0으로 끝납니다. 이 lab의 lint는 node --check 문법 검사입니다. 원문의 yarn set version stable은 새 프로젝트 선택 예이며 제공 lab은 packageManager에 적힌 4.18.0 기준을 유지합니다.

변형 과제: src/main.js의 출력 문장을 바꾼 뒤 yarn dev를 다시 실행합니다. lint script가 문법 검사만 한다는 점과 화면 앱을 검사하지 않는다는 점을 구분합니다.

package.json
packageManager
lockfile
pnpm install
workspace

메인 프로젝트
→ pnpm

Yarn 학습
→ 독립 lab

npm 오류 학습
→ 독립 lab

dev-env-step-01-pnpm-base

TaskFlow 메인: pnpm
Yarn 저장소: packageManager 우선 확인
Yarn 실습: 별도 lab
여러 lockfile 혼용 금지

pnpm install
pnpm dev

yarn --version
yarn install

dev-env-step-02-package-manager-choice

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

<!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>

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

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);

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; }

# TaskFlow 개발환경

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

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

## 2회차

메인 앱은 pnpm을 유지합니다. labs/yarn-modern은 독립 Yarn 실습입니다.

{
  "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"
  }
}

packages:
  - "apps/*"

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

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를 확인하세요.

nodeLinker: node-modules

{
  "name": "taskflow-yarn-lab",
  "private": true,
  "type": "module",
  "packageManager": "yarn@4.18.0",
  "scripts": {
    "dev": "node src/main.js",
    "lint": "node --check src/main.js"
  }
}

console.log('TaskFlow Yarn 독립 실습');

다음 학습

다음 글에서는 .env, .env.local, .env.development, .env.example의 역할을 나누고 저장소에 올려도 되는 값과 안 되는 값을 정리합니다.

다음 글: 환경변수 .env 파일 차이: local, example, development 기준

공식 문서

• Yarn Installation: https://yarnpkg.com/getting-started/install
• Yarn Corepack: https://yarnpkg.com/corepack
• Yarn Manifest: https://yarnpkg.com/configuration/manifest