TypeScript Path Aliases Not Working in Antigravity: Complete Fix Guide

You wrote @/components/Button and the red squiggle won't go away. The AI keeps generating ../../components/Button instead. If you've been developing in Antigravity and your path aliases simply aren't working, you're not alone — this is one of the most common setup issues developers hit when starting a new project.

Modern Next.js and Vite projects rely heavily on @/ aliases, but when Antigravity can't resolve them, it cascades into AI completions full of relative paths, persistent type errors, and imports that break at runtime. Let me walk you through the cause and fix, step by step.

Why Antigravity Can't Resolve Path Aliases

For Antigravity to recognize your path aliases, it needs to correctly read the paths field in your tsconfig.json (or tsconfig.paths.json). That process breaks down in a few predictable ways.

Missing baseUrl with paths defined: The paths field only works in combination with baseUrl. Without baseUrl, neither TypeScript itself nor Antigravity can resolve aliases.

Wrong workspace root: In monorepo setups or projects under subdirectories like apps/web/, the root Antigravity is pointed at doesn't match where tsconfig.json lives.

Broken extends inheritance: When you extends from packages like @tsconfig/nextjs, the paths field doesn't always inherit the way you'd expect.

The errors you'll see:

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

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

When these appear, treat it as a path resolution problem — not a type problem.

Step 1: Verify baseUrl and paths in tsconfig.json

Start here. This is the root cause more than 80% of the time.

// tsconfig.json — correct configuration
{
  "compilerOptions": {
    "baseUrl": ".",          // Required. Without this, paths doesn't work.
    "paths": {
      "@/*": ["./src/*"],    // Relative to baseUrl
      "@components/*": ["./src/components/*"],
      "@lib/*": ["./src/lib/*"]
    }
  }
}

// Common mistake: paths defined without baseUrl
{
  "compilerOptions": {
    "paths": {
      "@/*": ["./src/*"]    // This won't resolve without baseUrl
    }
  }
}

"baseUrl": "." means "use the directory where this tsconfig lives as the root." Some projects set it to "src", which is fine — just make sure your paths values are consistent with that choice.

Step 2: Check Antigravity's Workspace Root

Even with a correct tsconfig.json, Antigravity might be reading the wrong root directory.

How to check:

1. Press ⌘ + Shift + P (or Ctrl + Shift + P on Windows) and run TypeScript: Select TypeScript Version
2. Confirm Use Workspace Version is selected
3. Click the TypeScript version number in the status bar (bottom right) to verify which tsconfig.json is being loaded

Monorepo setups are especially prone to this. If you opened Antigravity from a subdirectory like apps/web/ rather than the repo root, the Language Server may be looking for tsconfig.json in the wrong place.

# Quick diagnostic: does tsconfig.json exist in your current directory?
ls tsconfig.json
 
# Check if paths are actually set
cat tsconfig.json | grep -A5 '"paths"'

Step 3: Framework-Specific Configurations

Next.js

Next.js 16 automatically sets up @/* aliases when you run create-next-app. If yours broke after manual edits, here's the correct setup:

Without src/ directory:

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

With src/ directory:

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

The src/ vs non-src/ distinction trips up a lot of developers. If you scaffolded with src/ and then moved files around, double-check which applies to your project.

Vite

Vite requires alias configuration in both vite.config.ts and tsconfig.json. Setting only one will give you a half-broken state.

// vite.config.ts — handles runtime/build resolution
import { defineConfig } from 'vite'
import path from 'path'
 
export default defineConfig({
  resolve: {
    alias: {
      '@': path.resolve(__dirname, './src'),
    },
  },
})

// tsconfig.json — handles TypeScript/Antigravity type resolution
{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@/*": ["./src/*"]
    }
  }
}

Missing vite.config.ts alias = build fails but types are fine. Missing tsconfig.json paths = types break but build works. You need both.

Step 4: Reset Antigravity's TypeScript Cache

After fixing your config, Antigravity may still be serving stale data from its cache.

First, quit Antigravity completely (⌘+Q / Ctrl+Q). Then clear the Language Server cache:

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

Restart Antigravity and reopen the affected file.

A lighter option that often works: ⌘ + Shift + P → Developer: Reload Window. Running this right after saving your tsconfig.json forces the Language Server to re-read the config without a full restart.

Step 5: Stop AI from Suggesting Relative Paths

Even after fixing tsconfig, the AI might keep proposing relative path imports — especially if your existing codebase has many examples of ../../ style imports that the AI learned from.

Add a rules file to your project root to explicitly guide the AI:

<!-- .antigravity/rules.md or AGENTS.md -->
## Import Rules
 
- Always use path aliases (@/) for imports
- Relative paths with 3+ levels (../../..) are not allowed
- Examples: @/components/Button, @/lib/utils, @/hooks/useAuth
- For files outside src/, use the root alias (@/)

In my experience, adding this file dramatically improves AI suggestion quality for imports. The "AI uses relative paths even though aliases work" issue is almost always caused by missing project context — not a bug in Antigravity.

Quick Checklist

Before moving on, run through these:

• tsconfig.json has both baseUrl and paths defined
• The paths values start with ./ (relative to baseUrl)
• Vite projects also have resolve.alias in vite.config.ts
• You've reloaded the Antigravity window after saving config
• You've closed and reopened the affected file

If none of this resolves it, run tsc --noEmit in Antigravity's terminal and look at the raw TypeScript output. If the error code isn't TS2307, the root cause is somewhere other than path resolution.

Path aliases are the kind of configuration you set once and forget — but when they're broken, they create a frustrating ripple effect through your entire development workflow, including AI quality. Once this is sorted, take a moment to add your import rules to .antigravity/rules.md and you'll find the AI starts suggesting cleaner, alias-based imports from that point on.