Yarn 기초 사용법: 설치부터 패키지 관리까지 처음 배우는 개발자를 위한 정리

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

Yarn이란 무엇인가

Yarn은 JavaScript 프로젝트에서 패키지를 관리하는 도구입니다. 여기서 패키지는 직접 만들지 않은 외부 코드 묶음을 뜻합니다. 예를 들어 React로 화면을 만들거나, axios로 요청을 보내거나, Vite로 개발 서버를 실행할 때 이런 도구들이 모두 패키지로 설치됩니다.

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

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

Yarn 설치와 버전 확인

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

yarn --version

명령어를 찾을 수 없다는 메시지가 나오면 Yarn이 아직 준비되지 않은 상태입니다. 최근 Node.js 환경에서는 Corepack을 통해 Yarn을 활성화하는 방식도 자주 사용합니다. 다만 설치 방식과 권장 흐름은 Node.js, Corepack, Yarn 버전에 따라 달라질 수 있으므로 발행 전에는 공식 문서의 현재 안내를 한 번 확인하는 것이 좋습니다.

corepack enable

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

• package.json: 프로젝트 이름, 스크립트, 의존성 목록이 들어 있습니다.
• yarn.lock: 설치된 패키지 버전 조합을 고정합니다.
• node_modules: 실제 패키지 파일이 설치되는 폴더입니다.
• .yarnrc.yml: Yarn 동작 방식을 설정하는 파일입니다.

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

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

mkdir my-app
cd my-app
yarn init -y

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에서 확인하면 됩니다.