Nuxt で TypeScript を利用する際の tsconfig 設定を整理する

はじめに

久しぶりに記事を書きます。最近インプットが多すぎて記事を書けなくなってきてしまっているので、インプットをちゃんと供養しないと...。

今回は、Nuxt で TypeScript を利用する際に tsconfig.json の設定によく迷いがちなので、改めて整理しようかなと思いこの記事を書くことにしました。

Nuxt で TypeScript を利用するには

まず、Nuxt で TypeScript を利用するにはまず vue-tsc のインストールが必要です。

npm install -D vue-tsc

また、　nuxt.config.ts には、最低限下記の設定があるといいでしょう。

nuxt.config.ts

export default defineNuxtConfig({
  typescript: {
    typeCheck: true,
  },
  // ...
})

Nuxt の tsconfig.json について

実は、Nuxt では自前のtsconfig.jsonを用意しなくても、

npx nuxt prepare

を実行すると、.nuxt/tsconfig.json を自動で出力してくれます。
また、Nuxt の AutoImport 機能によって、定義されているコンポーネントの型の定義などもパースしてよしなに .nuxt/tsconfig.json に出力してくれます。

Nuxt が生成した tsconfig.json だけを利用する問題点と解決法

自動で出力された、.nuxt/tsconfig.json を利用すれば、型チェックもできて嬉しい！と手放しで喜ぶには少し早いです。
いくつか .nuxt/tsconfig.json ベースでの開発には大きな問題点があります。

VSCodeがデフォルトで、.nuxt/tsconfig.json を読み込まない

まあまあ大きな問題点です。
これを解決するために、Nuxt は、以下の方法をお勧めしているようです。

プロジェクトルートに以下のように、

tsconfig.json

{
  "extends": "./.nuxt/tsconfig.json"
}

tsconfig.json を定義します。
こうすれば、Nuxt が自動生成した型の恩恵を受けつつ、VSCodeの恩恵も受けられます。

Nuxt が生成した、tsconfig.json と プロジェクトルートの tsconfig.json が共存する際の注意点

例えば、以下のようにディレクトリが構成されていたとします。

.
├── app/
│   ├── types/
│   │   └── nuxtSchema.d.ts
│   └── main.vue
├── node_modules
├── .nuxt
│   └── tsconfig.json
├── package.json
├── package-lock.json
├── tsconfig.json
└── nuxt.config.ts

この場合、app/types/nuxtSchema.d.ts に定義されているファイルは、nuxt/schema の型を以下のように、書き換えたいファイルだとします。

nuxtSchema.d.ts

declare module 'nuxt/schema' {
  interface PublicRuntimeConfig {
    ENV: 'development' | 'production'
  }
}
// It is always important to ensure you import/export something when augmenting a type
export {}

もちろん、プロジェクトルートの tsconfig.json では、定義されているディレクトリの子に存在する、このファイルを自動で読み取ることができます。しかし、 .nuxt/tsconfig.json はどうでしょうか。

皆さんなんとなく察しがつくかもしれませんが、
いくら nuxt prepare コマンドを実行しても *.d.ts ファイルは自動で読み取れません。

もし、declare を *.d.ts ファイルで、利用したい場合は、 nuxt.config.ts において追加で下記のように設定する必要があります。

nuxt.config.ts

export default defineNuxtConfig({
  typescript: {
    typeCheck: true,
    tsConfig: {
      include: ['../app/types/*.d.ts'], // .nuxt/tsconfig.json からの相対パス
    },
  },
  // ...
})

※ tsconfig.json をカスタマイズする際も同様で、nuxt.config.ts との整合性をとる必要があります。
エラーの再現をコメントに追記しました。
https://zenn.dev/link/comments/d9008dff66ab83

おわりに

今回は、Nuxt で TypeScript を利用する際の tsconfig 設定をする際の注意点と解決方法について詳しく説明しました。少し手間はかかりますが、Nuxt の AutoImport 機能はかなり強力なため、正しい設定を方法を学んで、快適な開発ライフを送ってみてください。