Antigravity で TypeScript のパスエイリアスが効かないときの原因と直し方

@/components/Button と書いたのに赤い波線が消えありません。AIが生成したコードには ../../components/Button と書かれている——Antigravityで開発していると、パスエイリアスが全く機能しない場面に遭遇することがあります。

Next.js や Vite プロジェクトでは @/ エイリアスが当たり前のように使われていますが、Antigravity がこのエイリアスを認識できていないと、AI の補完提案が相対パスだらけになり、型エラーが消えない、インポートが壊れるといった問題が連鎖します。ここでは原因を段階的に切り分けて確実に解決する方法をお伝えします。

なぜAntigravityはパスエイリアスを認識できないのか

Antigravity がパスエイリアスを解決するには、tsconfig.json（または tsconfig.paths.json）の paths フィールドを正しく読み込む必要があります。ところが、以下のような状況でこれが崩れます。

よくある原因を 3 つ挙げます。

baseUrl が未設定のまま paths を定義している: paths は baseUrl との組み合わせで機能します。baseUrl が欠けていると TypeScript 本体も Antigravity も解決できません。

ワークスペースのルートが正しくない: モノレポ構成や apps/web/ のようなサブディレクトリ構成で、Antigravity が開いているルートと tsconfig.json のある場所がずれているケースです。

tsconfig.json の継承（extends）が正しく展開されていない: Next.js の @tsconfig/nextjs を extends しているとき、paths の継承が想定通りに機能していないことがあります。

エラーメッセージとしては以下のようなものが代表的です。

Cannot find module '@/components/Button' or its corresponding type declarations. ts(2307)

Module not found: Can't resolve '@/lib/utils'

これらが出ているときは、型の問題ではなくパス解決の問題として切り分けてください。

Step 1: tsconfig.json の baseUrl と paths を確認する

最初に確認すべきは tsconfig.json の基本設定です。

// tsconfig.json（正しい設定例）
{
  "compilerOptions": {
    "baseUrl": ".",          // 必須。省略するとpathsが機能しない
    "paths": {
      "@/*": ["./src/*"],    // baseUrlからの相対パス
      "@components/*": ["./src/components/*"],
      "@lib/*": ["./src/lib/*"]
    }
  }
}

// よくある間違い：baseUrl が欠けている
{
  "compilerOptions": {
    "paths": {
      "@/*": ["./src/*"]    // baseUrl なしでは解決されない
    }
  }
}

baseUrl: "." は「このファイルがあるディレクトリを基点とする」という意味です。"src" を baseUrl にしているプロジェクトも多いですが、その場合は paths の値も調整が必要です。

Step 2: Antigravityのワークスペース設定を確認する

tsconfig.json が正しくても、Antigravity が参照しているルートディレクトリと tsconfig.json の場所がずれていることがあります。

確認手順は次の通りです。

⌘ + Shift + P（Windows: Ctrl + Shift + P）を押して「TypeScript: Select TypeScript Version」を実行します
「Use Workspace Version」が選択されているか確認します
ステータスバー右下の TypeScript バージョン番号をクリックして、正しい tsconfig.json が読み込まれているか確認します

モノレポ構成の場合、Antigravity で プロジェクトのルートではなく apps/web/ のようなサブディレクトリを開いている場合に問題が起きやすいです。以下のコマンドで診断できます。

# 開いているディレクトリからtsconfig.jsonが見えるか確認
ls tsconfig.json
 
# paths設定があるか確認
cat tsconfig.json | grep -A5 '"paths"'

Step 3: Next.js・Vite それぞれの注意点

Next.js プロジェクトの場合

Next.js 16 では create-next-app 時に自動で @/* エイリアスが設定されます。ただし、tsconfig.json を手動で編集した後に壊れることがあります。

src/ ディレクトリなしの場合：

{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@/*": ["./*"]
    }
  }
}

src/ ディレクトリありの場合：

{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@/*": ["./src/*"]
    }
  }
}

src/ の有無でパスが変わる点が、混乱の原因になりやすい部分です。create-next-app 後にそのまま設定を継承しているのに壊れた、という場合はここを確認してみてください。

Vite プロジェクトの場合

Vite では vite.config.ts と tsconfig.json の両方にエイリアスを設定する必要があります。片方だけ設定してもどちらかが壊れます。

// vite.config.ts
import { defineConfig } from 'vite'
import path from 'path'
 
export default defineConfig({
  resolve: {
    alias: {
      '@': path.resolve(__dirname, './src'),
      // Viteのビルド時パス解決に必要
    },
  },
})

// tsconfig.json（Viteプロジェクト）
{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@/*": ["./src/*"]
    }
  }
}

この 2 つが揃って初めて、ビルドも型チェックもエイリアスが機能します。「ビルドは通るが型エラーが出る」「型エラーは出ないがビルドが失敗する」という半壊状態は、どちらか一方しか設定していないことがほとんどです。

Step 4: Antigravityのキャッシュをリセットする

設定を直しても Antigravity が古い情報をキャッシュしていることがあります。以下の手順でリセットしてください。

まず Antigravity を完全に終了（⌘+Q / Ctrl+Q）します。次に、Language Server のキャッシュを削除します。

# macOS / Linux
rm -rf ~/.antigravity/typescript-cache
 
# Windows
rd /s /q %APPDATA%\antigravity\typescript-cache

その後 Antigravity を再起動して、問題のあるファイルを開き直してください。

より手軽な方法として、⌘ + Shift + P → 「Developer: Reload Window」で Antigravity のウィンドウを再読み込みする方法も効果的です。tsconfig.json を保存した直後にこれを実行すると、Language Server が設定を再読み込みします。

Step 5: AIの補完提案が相対パスになるのを防ぐ

tsconfig.json の設定を直しても、Antigravity の AI が相対パスを提案し続ける場合があります。これは AI がプロジェクトの既存コードパターンから相対パスを「正しい書き方」と判断しているためです。

プロジェクトルートに .antigravity/rules.md（または AGENTS.md）を置いて、エイリアスの使用を明示的に指示するのが効果的です。

## インポートルール
 
- 必ずパスエイリアス（@/）を使用すること
- 相対パス（../../）での3階層以上のインポートは禁止
- 例：@/components/Button, @/lib/utils, @/hooks/useAuth
- src/ディレクトリ外へのインポートはルートからのパス（@/）を使う

私の経験では、このルールファイルを置いた後の AI 補完の質が大幅に改善されました。「エイリアスが使えるはずなのに相対パスが提案される」という問題は、AI への文脈提供不足が原因であることが多いです。

確認チェックリスト

設定を変更したら、以下を順番に確認してください。

tsconfig.json に baseUrl と paths の両方がある
paths の値が baseUrl からの相対パス（./src/* のように ./ から始まる）になっている
Vite プロジェクトは vite.config.ts の alias も設定している
Antigravity のウィンドウを再読み込みした
問題のあるファイルを一度閉じて再度開いた

それでも解決しない場合、Antigravity 内のターミナルで tsc --noEmit を実行して TypeScript のエラー出力を直接確認してみてください。エラーコードが「TS2307」でなければ、パス解決以外の原因が考えられます。

パスエイリアスの設定は、一度正しく整えてしまえばほぼ触ることのない部分です。ただ、プロジェクト初期に詰まると開発の立ち上がりが遅くなりますし、AI の補完精度にも直結します。この記事の手順で解決できれば、あとは .antigravity/rules.md でAIへの指示を充実させて、快適な開発環境を整えていただければと思います。