Yarn PnP 환경에서 TypeScript "Cannot find module" 오류 해결하기

벌꿀오소리·2025년 10월 2일

React

목록 보기

2/2

1. 문제 개요

Yarn PnP 환경에서 TypeScript 프로젝트를 처음 실행하면 아래와 같이 많은 “Cannot find module” 에러 메시지가 출력되는 경우가 있습니다.

이 글에서는 왜 이런 오류가 발생하는지와 어떻게 해결할 수 있는지를 정리해보겠습니다.

2. 환경 소개

이 글에서 다루는 환경은 다음과 같습니다. (2025.10.02 기준)

Yarn : Berry (v3.9.2, Plug'n'Play 방식 사용)
TypeScript : v5.9.3
IDE : Cursor (v.1.7.28), VSCode (v1.99.3)

3. 문제 원인

Yarn 2(Berry)부터는 기본적으로 Plug'n'Play(PnP) 방식을 사용합니다.
이 방식은 기존처럼 node_modules 폴더에 의존성을 풀어 넣는 대신, 패키지를 가상의 파일 시스템에서 직접 참조합니다.

문제는 TypeScript와 IDE(특히 VSCode)가 기본적으로 node_modules 구조를 전제로 동작한다는 점입니다.

TypeScript는 타입 정의 파일(@types/*)이나 모듈 경로를 node_modules 안에서 찾습니다.
VSCode 역시 내부적으로 node_modules를 기준으로 TypeScript SDK를 로드합니다.

하지만 Yarn PnP 환경에서는 node_modules가 존재하지 않기 때문에, TypeScript가 의존성을 찾지 못하고 "Cannot find modules", TS2307 오류가 발생하게 됩니다.

즉, 이 문제는 "Yarn PnP 방식"과 "TypeScript·VSCode의 기본 모듈 해석 방식"이 서로 맞지 않아 발생한 것입니다.

이 불일치를 해결하기 위해 Yarn에서는 별도의 SDK(@yarnpkg/sdks)와 설정(yarnrc.yml, nodeLinker: pnp)을 제공하고 있습니다.
출처 : https://yarnpkg.com/getting-started/editor-sdks

4. 해결 방법

방법 1.@yarnpkg/sdks 설치 후 VSCode SDK 설정하기

이 방법은 Yarn이 제공하는 공식 SDK 패키지를 설치해서 IDE와 연동하는 방법입니다.

yarn add @yarnpkg/sdks -D
yarn dlx @yarnpkg/sdks vscode

@yarnpkg/sdks : Yarn SDK를 설치해 VSCode가 Yarn PnP 환경을 이해할 수 있도록 도와줍니다.
yarn dlx @yarnpkg/sdks vscode : VSCode에 필요한 TypeScript/ESLint SDK 파일을 자동 생성하여 올바른 참조가 가능하게 합니다.

Cursor 기준 좌측 하단의 Allow 메시지 클릭 시 VSCode에서 TypeScript 관련 오류가 사라지고, PnP 환경을 제대로 인식하게 됩니다.

방법 2. yarnrc.yml 설정 + SDK 적용하기

이 방법은 Yarn Berry 버전을 명시적으로 설정하고, 이후 SDK를 적용하는 방법입니다.

# Yarn을 Berry 버전(PnP)으로 전환
yarn set version berry

# 생성된 .yarnrc.yml 파일에 nodeLinker: pnp 추가

# VSCode SDK 적용
yarn dlx @yarnpkg/sdks vscode

yarn set version berry : Yarn을 Berry 버전으로 설정하면서 .yarnrc.yml 파일이 생성됩니다.
nodeLinker: pnp 추가
yarn dlx @yarnpkg/sdks vscode : VSCode 환경에서 Yarn PnP를 사용할 수 있도록 일회성 SDK 파일을 다운로드 및 적용합니다.