[Vue] 기존 Vue 프로젝트에 타입스크립트 도입하기

Step1: Migrate from Vue CLI to Vite

Vue CLI를 사용하고 있다면, TypeScript를 좀 더 안정적으로 사용하기 위해 Vite로 마이그레이션하기

Vue CLI also provides TypeScript support, but is no longer recommended.

If you are currently using Vue 3 + TypeScript via Vue CLI, we strongly recommend migrating over to Vite. We are also working on CLI options to enable transpile-only TS support, so that you can switch to vue-tsc for type checking.


*출처: Note on Vue CLI and ts-loader

 

• 빌드툴 마이그레이션을 통해 얻을 수 있는 이점
  • 안정된 타입스크립트 개발 환경
  • 빠른 속도의 개발 서버 (Hot Module Replacement)
• 아래 자료들 참고했다.
  • How to migrate from Vue CLI to Vite
  • https://medium.com/nerd-for-tech/from-vue-cli-to-vitejs-648d2f5e031d
  • https://vitejs.dev/guide/features.html#typescript
  • https://youtu.be/PAT7SbdTBjI?si=tXSQPoK1xJDL6kKV
• 마이그레이션 이후 개발 서버 실행 속도 뿐만 아니라 빌드 속도도 상당히 향상됨.
  • 개발 서버 실행 속도: 22273 ms(22.3초) → 1610 ms(1.6초)
  • 빌드 속도: 2분19초(139 초) → 38초
• 트러블슈팅
  • path alias 설정은 vite.config.js에서도 해줘야 하고 jsonconfig.json에서도 해줘야 한다.
    • 전자는 빌드할 때 알맞은 경로 찾아갈 수 있도록 설정하는 거..
    • 후자는 에디터(VS Code)가 인지할 수 있도록 설정하는 거.. 경로 자동완성, 파일 바로가기 등 작업 환경 편하게 하기 위함.
  • vite에서 serve 명령어는 '프로덕션 빌드를 로컬에서 미리보기' 위한 목적으로 사용된다.
  • dev server 실행할 때나 build할 때 mode 지정은 기존과 동일하게 --mode={mode} 붙이면 됨.
    (참고: https://ko.vitejs.dev/guide/env-and-mode.html#modes)
  • .env.{mode} 파일의 환경 변수 이름도 바꿔줘야 됨 ㅠ vue-cli랑 환경변수 prefix가 다름..
    - prefix in vue-cli: VUE_APP_{}
    - prefix in vite: VITE_{}
    "Vite에서 접근 가능한 환경 변수는 일반 환경 변수와 구분을 위해 VITE_ 라는 접두사를 붙여 나타냅니다." (참고: https://ko.vitejs.dev/guide/env-and-mode.html#env-files)
  • production 모드로 빌드할 때 주의할 점: env 파일명은 기존처럼 .env.prod로 하면 인식을 못한다. .env.production이어야 한다.
    • 참고: https://www.inflearn.com/questions/652043/build시-환경변수-설정방법

Step2: Use Volar instead of Vetur in VS Code

VS Code 익스텐션 교체 - Vetur에서 Volar로 바꿔주기

• Vue2에선 Vetur가 Vue의 공식 VS Code 익스텐션이었는데 Vue3에선 Volar로 바뀌었다고 한다.

Volar is the official VSCode extension that provides TypeScript support inside Vue SFCs, along with many other great features.

Volar replaces Vetur, our previous official VSCode extension for Vue 2. If you have Vetur currently installed, make sure to disable it in Vue 3 projects.

• How? → https://stackoverflow.com/questions/74405512/detected-vetur-enabled-consider-disabling-vetur-and-use-volar-plugins-vetur-in
  • TLDR: uninstall Vetur and keep Volar (official recommended extension).

Step3: Install TypeScript Vue Plugin in VS Code

TypeScript가 .vue 파일도 인식할 수 있도록 돕는 TypeScript Vue Plugin 설치하기

• TypeScript는 기본적으로 .ts 또는 .js 파일만 인식하기 때문에 이 플러그인을 설치해야 .vue 파일 내에서도 타입 체크, 자동 완성, 오류 검사 등의 TypeScript 기능이 정상적으로 작동할 수 있다.

Step4: Configure tsconfig.json

tsconfig.json 파일 추가하기

• 기존에 존재하던 jsconfig.json 파일을 tsconfig.json으로 바꾼 뒤 compiler 옵션을 몇 가지 더 추가해줬다.
• 디렉토리에 tsconfig.json 파일이 있다면, 이는 그 디렉토리가 타입스크립트 프로젝트의 루트 디렉토리임을 의미한다.
• create-vue를 통해 생성한 프로젝트에는 tsconfig.json이 자동으로 포함되어 있지만, 우리 프로젝트처럼 수동으로 tsconfig.json을 추가해야 하는 경우에는 다음 내용을 참고하라고 한다. :
  1. compilerOptions.isolatedModules는 true로 설정되어 있다. Vite는 타입스크립트를 트랜스파일링(transpiling)하기 위해 esbuild를 사용하며 단일 파일 변환(transpile) 제한을 받기 때문이다.
     • 트랜스파일링이란 어떤 언어로 쓰여진 소스 코드를, 추상화 수준이 비슷한 다른 언어로 변환하는 과정을 의미한다. (출처: Compiling vs Transpiling - Hashnode)
     • "번역(translate)과 컴파일(compile)이 합쳐져 트랜스파일이라는 신조어가 탄생했습니다. 소스코드를 동일한 동작을 하는 다른 형태의 소스코드로 변환하는 행위를 의미합니다. 결과물이 여전히 컴파일되어야 하는 소스코드이기 때문에 컴파일과는 구분해서 부릅니다." (출처: 이펙티브 타입스크립트 3번 주석)
     • 이러한 트랜스파일링 작업을 하는 툴인 트랜스파일러로서 Babel이 자주 사용된다.
       • Babel은 자바스크립트 컴파일러로서 ECMAScript 2015+ 코드를 브라우저 또는 자바스크립트 실행 환경에 호환되는 이전 자바스크립트 버전으로 변환하기 위해 주로 사용된다.
     • ‘단일 파일 변환 제한’을 받는다는 의미
       • 우선 compilerOptions.isolatedModules 옵션이 무엇인지 알아보자.
         • 타입스크립트를 사용하여, 타입스크립트로부터 자바스크립트 코드를 생산해낼 수 있는데, 이러한 변환 작업은 타입스크립트가 아닌 다른 트랜스파일러들을 통해 할 수도 있다. 그런데 이러한 다른 트랜스파일러들은 한번에 하나의 파일만 처리할 수 있다. 즉, 전체 타입 시스템에 대한 이해가 필요한 경우 이러한 트랜스파일러들로는 코드 변환을 할 수 없다는 의미이다.
         • 이러한 제약으로 인해 특정 타입스크립트 기능들에 있어서 런타임 이슈가 발생할 수 있다.
         • isolatedModules 플래그를 설정해두면, 타입스크립트로 어떤 코드를 작성할 때 만약 그 코드가 단일 파일 트랜스파일 과정을 통해 올바르게 변환될 수 없는 경우 타입스크립트 경고를 통해 이를 알려준다. (이러한 경우에 대한 예시는 위 링크 참고)
       • 이 내용을 토대로 생각해보면, Vite는 트랜스파일러로서 esbuild를 사용하고, esbuild 역시 한번에 하나의 파일만 처리할 것이므로 특정 상황에서는 코드 변환에 대한 제약이 존재한다는 의미로 해석할 수 있다. 그리고 이러한 제약으로 인해 발생할 수 있는 런타임 이슈를 예방하기 위해 tsconfig.json에 compilerOptions.isolatedModules: true 옵션을 설정하라는 것으로 이해했다.
  2. 우리 프로젝트처럼 Options API를 사용하는 경우에는, 컴포넌트 옵션 내에서 this에 대한 타입 검사를 위해서 compilerOptions.strict를 true로 설정하거나 이게 어렵다면 이 플래그의 일부인 compilerOptions.noImplicitThis를 활성화해둬야 한다. 이렇게 하지 않으면 this는 any로 취급된다.
  3. 빌드툴에서 파일 경로에 대한 단축 별명(resolver alias, path alias - 예: @/*)을 설정해두었다면, compilerOptions.paths을 통해 타입스크립트 쪽에도 이와 동일하게 설정해줘야 한다.
• 우리 프로젝트의 경우 js → ts로 점진적 개선을 해나가야 하는 상황이라 한동안은 js와 ts가 병존해야 하므로 allowJs 옵션도 true로 설정해뒀다.

 

Step5: Volar Takeover Mode

성능 향상을 위해 Volar의 Takeover Mode 설정하기 (VS Code + Volar 사용하는 경우만 해당)

• Vue SFC와 타입스크립트를 함께 사용할 수 있도록 하기 위해 Volar는 Vue를 지원하는 별도의 TS language service 인스턴스를 생성하여 Vue SFC 내에서 사용한다. 동시에, 일반 타입스크립트 파일들은 여전히 VS Code의 빌트인 TS language service가 관리한다. 그래서 타입스크립트 파일에서 Vue SFC 파일을 불러오기 위해서는 TypeScript Vue Plugin (Volar)이 필요한 것이다.
• 이러한 기본 구성은 동작을 하기는 하나, 각 프로젝트에서 두 개의 TS language service인스턴스(하나는 Volar, 다른 하나는 VS Code 빌트인 서비스)가 돌아가다보니 비효율적이기도 하고 규모가 큰 프로젝트에서는 성능 이슈로 이어질 수도 있다.
• Volar는 성능 향상을 위해 Takeover Mode라는 기능을 제공한다. (takeover - 인계/인수, 장악) Takeover Mode에서는 하나의 TS language service 인스턴스만을 사용하여 Vue와 타입스크립트 파일 양쪽에 대한 지원을 제공한다.
• Takeover Mode를 설정하려면 우선 다음과 같이, 프로젝트의 워크스페이스 내에서만 VS Code 빌트인 TS language service를 비활성화해야 한다. :

https://vuejs.org/guide/typescript/overview.html#volar-takeover-mode

 

Step6: Install typescript-eslint

eslint가 TypeScript 코드를 인식하도록 typescript-eslint 설치하기

• 설치 방법은 https://typescript-eslint.io/getting-started 참고!
• 문서에 나와있는대로 이거 설치하고 .eslintrc.cjs 파일도 만들고 하라는대로 했는데 .vue 파일에서 다음과 같이 eslint 에러가 떴다. :

• 스택오버플로우에서 검색해보니 vue-eslint-parser를 써야 된다고 했다. 그래서 일단 이것도 설치했다. 그리고 .eslintrc.cjs 파일에서도 수정할 부분이 있었다.
  • 참고: Eslint Vue 3 Parsing error: '>' expected.eslint

Eslint Vue 3 Parsing error: '>' expected.eslint

/* eslint-env node */
module.exports = {
  extends: ["eslint:recommended", "plugin:@typescript-eslint/recommended"],
  parser: "@typescript-eslint/parser",
  plugins: ["@typescript-eslint"],
  root: true,
};