[Vue] 오픈소스 이슈 제보 후기

vue(404)... 무슨 에러지?

Vue 기반의 자바스크립트 프로젝트를 진행하던 중, 팀원이 프로젝트를 Github에서 clone 받고 .vue 파일을 열자마자

이해할 수 없는 에러를 마주했습니다.

 

vue(404): Write global types file failed.  
Please ensure that "node_modules" exists and "vue" is a direct dependency,  
or set "vueCompilerOptions.globalTypesPath" in "tsconfig.json" manually.

 

Write global types file failed. Please ensure that "node_modules" exists and "vue" is a direct dependency, or set "vueCompilerOptions.globalTypesPath" in "tsconfig.json" manually.vue(404)

 

"우리는 TypeScript도 안 쓰고, Volar 확장도 설치 안 했는데... 왜?

구글에 검색한 결과 최근 3일 전 정도 쯤 부터 이 오류를 겪은 사람들이 존재했습니다.

버전업 되면서 발생한 오류로 추측했고,

이 글은 그 오류를 계기로 직접 Vue 공식 저장소에 오픈소스 issue를 제보하고, 공식 답변에 대한 정리한 글입니다.

 

 

상황정리

• 프로젝트: Vue 3 + Vite 기반의 JavaScript-only 프로젝트
• 환경:
  - TypeScript 사용 안 함
  - Volar 확장 설치 안 함
  - .vue 파일을 VSCode에서 열었을 뿐
• 발생 시점:
  - GitHub 프로젝트를 clone한 직 후
  - npm install 완료
  - VSCode를 재시작하지 않은 상태

 

증상

.vue 파일을 열자마자 VSCode에서 다음 오류 발생:

vue(404): Write global types file failed. Please ensure that "node_modules" exists...

 

 

해결 방법

처음에는 맨 아래에 있는 방법으로 진행했지만..
다른 컴퓨터로 다른 시도를 해봤습니다.

그 어떤 설정도 건드리지 않고, 그냥 npm install 한 다음 VSCode를 재시작만 해도 에러는 사라졌습니다.

 

 

그럼 이건 버그가 아닌 건가?

버그는 아니지만, 사용자는 충분히 혼란스러울 수 있습니다.
특히 처음 Vue를 사용하는 초보 개발자나 TypeScript를 사용하지 않는 경우, 언어 도구의 내부 동작에 익숙하지 않은 개발자들에게 말입니다.

 

그래서 저는 이 문제를 직접 Vue Opensource에 이슈로 제보했습니다.

https://github.com/vuejs/language-tools/issues/5554

vue(404) error on opening .vue file after fresh clone – global types path or vue dependency warning · Issue #5554 · vuejs/la

 

간단히 요약하면, 아래와 같이 제안했습니다.

• JS-only project에서 .vue 파일 열자마자 vue(404) 오류 발생
• node_modules가 존재해도 VSCode를 재시작하지 않으면 오류 계속 발생
• 이걸 치명적인 버그로 보긴 어렵지만, DX 측면에서 개선 여지가 있다고 조심히 생각함
• Waiting for dependencies.... 같은 메세지나 restart 안내가 있다면 좋겠다고 제안

 

공식 답변 요약

Vue 팀에서는 다음과 같은 피드백을 주었습니다.

 

왜 오류가 발생했는가?

• .vue 파일을 npm install 전에 열면, 언어 서버가 제대로 초기화되지 않음.
• npm install 이후에도 VSCode를 재시작하지 않으면, 여전히 오류가 발생할 수 있음
• 이는 언어 서버가 깨진 상태로 초기화되었기 때문이며, 단순히 의존성이 생겼다고 자동으로 회복되지는 않음.

자동 감지는 왜 불가능한지?

"의존성이 아직 설치되지 않은 것인지, 아니면 애초에 npm 환경이 아닌 프로젝트인지 언어 서버는 이를 구분할 수 없다"

 

• 즉, 언어 서버 입장에서는 "지금 기다려야 하는 상태인지 아닌지"를 판단할 수 있는 방법이 없음
• 따라서 "자동으로 에러를 숨기거나 조건부로 지연하는 처리는 어렵다"고 답변 받았습니다.

개선 가능성?

• 사용자가 혼란을 느끼지 않도록, 오류 메세지에 vue.action.restartServer 명령어를 실행하라는 안내 문구를 추가하는 방안은 긍정적으로 고려 중이라고 합니다.

 

추가로 알게 된 사실

• .vue 파일의 언어 지원(SFC) 기능은 JavaScript-only 프로젝트에서도 내부적으로 TypeScript에 의존하고 있었습니다.
• 즉, tsconfig.json이 없거나 TypeScript를 직접 사용하지 않더라도 언어 서버 내부 동작에는 TypeScript가 필요하며, TypeScript관련 오류 메세지를 완전히 숨기는 건 불가능하다는 것에 대해 알았습니다.

 

 

 

---

해결 방법(이렇게 안해도 됨)

1. jsconfig.json 또는 tsconfig.json 파일 생성/수정

vue-global-types.d.ts

{
  "compilerOptions": {
    "target": "esnext",
    "module": "esnext",
    "allowJs": true,
    "checkJs": false
  },
  "vueCompilerOptions": {
    "globalTypesPath": "./vue-global-types.d.ts"
  },
  "exclude": ["node_modules"]
}

 

이 설정은 Volar에게 "전역 타입을 이 경로에 한 번만 생성해달라"고 알려주는 역할을 합니다.

 

2. .gitignore에 파일 무시 추가

 

vue-global-types.d.ts

 

자동 생성되는 타입 파일이므로 git에 올릴 필요가 없습니다.

 

3. VSCode 재시작

변경사항을 적용하려면 VSCode를 완전히 종료 후 다시 실행해주세요

 

 

정리

이 오류가 뜬다면 당황하지 마시고! 위와 같이 해결하시면 됩니다.

전역 타입 경로를 명시하고 .gitigonore에만 추가해주면 됩니다.