TypeScript

Nuxt는 완전한 타입 지원을 제공하며, 코딩 시 정확한 타입 정보를 쉽게 활용할 수 있도록 유용한 단축 기능을 제공합니다.

타입 검사

기본적으로 Nuxt는 성능상의 이유로 nuxt dev 또는 nuxt build를 실행할 때 타입 검사를 수행하지 않습니다.

빌드 또는 개발 시점에 타입 검사를 활성화하려면 vue-tsc와 typescript를 개발 의존성으로 설치하세요:

npm install --save-dev vue-tsc typescript

그런 다음 nuxt typecheck 명령을 실행하여 타입을 검사하세요:

Terminal
npx nuxt typecheck

빌드 또는 개발 시점에 타입 검사를 활성화하려면, nuxt.config 파일에서 typescript.typeCheck 옵션을 사용할 수도 있습니다:

nuxt.config.ts
export default defineNuxtConfig({
  typescript: {
    typeCheck: true,
  },
})

자동 생성 타입

Nuxt 프로젝트는 올바르게 동작하기 위해 자동 생성된 타입에 의존합니다. 이 타입들은 .nuxt 디렉터리에 저장되며, 개발 서버를 실행하거나 애플리케이션을 빌드할 때 생성됩니다. nuxt prepare를 실행하여 이 파일들을 수동으로 생성할 수도 있습니다.

.nuxt 디렉터리 내부에 생성되는 tsconfig.json 파일에는 프로젝트를 위한 권장 기본 TypeScript 설정과 자동 임포트, API 라우트 타입, #imports, ~/file, #build/file 같은 경로 별칭 등에 대한 참조가 포함되어 있습니다.

Nuxt는 이 설정에 의존하며, Nuxt 모듈도 이를 확장할 수 있습니다. 이러한 이유로 tsconfig.json 파일을 직접 수정하는 것은 권장되지 않습니다. 직접 수정하면 중요한 설정이 덮어써질 수 있기 때문입니다. 대신 nuxt.config.ts를 통해 확장하세요. 설정을 확장하는 방법은 여기에서 더 알아보세요.
Daniel Roe가 Nuxt에 내장된 별칭에 대해 설명하는 영상을 시청해 보세요.

프로젝트 참조

Nuxt는 타입 검사 성능을 향상하고 더 나은 IDE 지원을 제공하기 위해 TypeScript 프로젝트 참조를 사용합니다. 이 기능을 통해 TypeScript는 코드베이스를 더 작고 관리하기 쉬운 단위로 나눌 수 있습니다.

Nuxt가 프로젝트 참조를 사용하는 방법

nuxt dev, nuxt build 또는 nuxt prepare를 실행하면, Nuxt는 애플리케이션의 서로 다른 부분을 위해 여러 개의 tsconfig.json 파일을 생성합니다.

  • .nuxt/tsconfig.app.json - app/ 디렉터리 내 애플리케이션 코드에 대한 설정
  • .nuxt/tsconfig.node.json - nuxt.config.ts 및 다른 컨텍스트 외부의 파일에 대한 설정
  • .nuxt/tsconfig.server.json - 서버 사이드 코드에 대한 설정(해당되는 경우)
  • .nuxt/tsconfig.shared.json - 앱과 서버 컨텍스트 간에 공유되는 코드(타입 및 환경 비의존 유틸리티 등)를 위한 설정

각 파일은 해당 컨텍스트에 맞는 의존성을 참조하도록 구성되어 있으며, 그 컨텍스트에 최적화된 타입 검사를 제공합니다.

하위 호환성을 위해 Nuxt는 여전히 .nuxt/tsconfig.json을 생성합니다. 그러나 더 나은 타입 안정성과 성능을 위해 새로운 설정 파일들(.nuxt/tsconfig.app.json, .nuxt/tsconfig.server.json 등)과 함께 TypeScript 프로젝트 참조를 사용할 것을 권장합니다. 이 레거시 파일은 Nuxt의 향후 버전에서 제거될 예정입니다.

프로젝트 참조의 이점

  • 더 빠른 빌드: TypeScript가 변경되지 않은 프로젝트의 재빌드를 건너뛸 수 있습니다.
  • 더 나은 IDE 성능: IDE가 더 빠른 IntelliSense와 오류 검사를 제공할 수 있습니다.
  • 격리된 컴파일: 애플리케이션의 한 부분에서 발생한 오류가 다른 부분의 컴파일을 막지 않습니다.
  • 더 명확한 의존성 관리: 각 프로젝트가 자신의 의존성을 명시적으로 선언합니다.

프로젝트 참조로 타입 보강하기

프로젝트가 여러 타입 컨텍스트로 나뉘어 있기 때문에, 타입이 올바르게 인식되도록 올바른 컨텍스트 내에서 타입을 보강(augment) 하는 것이 중요합니다. 해당 디렉터리 외부에 위치한 보강은, 적절한 컨텍스트에 명시적으로 포함되지 않는 한 TypeScript에서 인식되지 않습니다.

예를 들어, app 컨텍스트의 타입을 보강하려면, 보강 파일은 app/ 디렉터리에 위치해야 합니다.

마찬가지로:

  • server 컨텍스트의 경우, 보강 파일을 server/ 디렉터리에 두세요.
  • 앱과 서버 간에 공유되는 타입의 경우, 파일을 shared/ 디렉터리에 두세요.
해당 컨텍스트 외부의 파일에서 특정 타입 컨텍스트를 보강하는 방법에 대해 더 알아보려면 모듈 작성자 가이드를 참고하세요.

엄격 검사

TypeScript에는 프로그램에 더 많은 안전성과 분석을 제공하기 위한 여러 검사 기능이 포함되어 있습니다.

엄격 검사는 더 높은 타입 안정성을 제공하기 위해 typescript.typeCheck 옵션이 활성화된 경우 Nuxt에서 기본적으로 활성화됩니다.

현재 코드베이스를 TypeScript로 변환 중이라면, nuxt.config에서 strict를 false로 설정하여 엄격 검사를 일시적으로 비활성화하고 싶을 수 있습니다:

nuxt.config.ts
export default defineNuxtConfig({
  typescript: {
    strict: false,
  },
})