Vite “Failed to Resolve Import” Alias: Align tsconfig, Vite, and Vitest

The short fix: give Vite an absolute alias#

For a project where @ should point to src, add an alias to vite.config.ts:

1
import { fileURLToPath, URL } from 'node:url'
2
import { defineConfig } from 'vite'
3

4
export default defineConfig({
5
  resolve: {
6
    alias: {
7
      '@': fileURLToPath(new URL('./src', import.meta.url)),
8
    },
9
  },
10
})

Then this import has one clear Vite-side meaning:

1
import Button from '@/components/Button.vue'

The Vite resolve.alias documentation recommends absolute filesystem paths for filesystem aliases. A relative value such as '@': './src' is not equivalent: Vite passes relative replacement values through as-is, which can make resolution depend on the importing file or tool.

Keep the TypeScript mapping too, so the editor, type checker, and Vite agree:

1
{
2
  "compilerOptions": {
3
    "baseUrl": ".",
4
    "paths": {
5
      "@/*": ["src/*"]
6
    }
7
  }
8
}

The exact baseUrl and paths shape may differ in a monorepo, but the important boundary is the same: TypeScript and Vite each need a resolver that understands the alias.

Why tsconfig.json alone is not enough#

TypeScript describes paths as a way to tell the compiler where a module name may be found. The setting does not change the import text emitted by TypeScript, and another tool must implement the runtime or bundler mapping.

That distinction explains a common sequence:

1. The editor can jump to @/lib/api.
2. tsc --noEmit passes.
3. Vite fails while scanning the module graph.

Nothing is contradictory here. The first two checks use TypeScript’s resolver; the third uses Vite’s resolver. Configure both or choose a supported bridge between them.

Choose one Vite-side mapping strategy#

An explicit resolve.alias is the most portable option. It is easy to inspect, works without a plugin, and makes the filesystem target obvious.

Current Vite documentation also exposes resolve.tsconfigPaths. When enabled, Vite reads paths from the relevant TypeScript configuration:

1
import { defineConfig } from 'vite'
2

3
export default defineConfig({
4
  resolve: {
5
    tsconfigPaths: true,
6
  },
7
})

Use this only when the option exists in the Vite version used by the project and the selected tsconfig describes the imports you actually build. It is not a reason to leave a stale or ambiguous paths configuration in place. Packages with non-JavaScript extensions may need explicit inclusion, and a monorepo may require a deliberate project root.

Vitest uses Vite’s resolution model but also has an alias test option. If vitest.config.ts is separate from vite.config.ts, confirm that the test configuration inherits the Vite config or repeats the alias intentionally. A passing Vite dev server does not prove that a test runner started with a different root or config file can resolve the same import.

Debug the resolver boundary, not the browser#

When the alias still fails, check the smallest set of facts that changes resolution:

• Path case: @/Components/Button and @/components/Button are different on case-sensitive filesystems.
• Real file location: confirm the target exists under the directory the alias points to.
• Project root: run Vite from the package whose config and tsconfig.json you inspected, especially in a workspace.
• Config file: make sure the command is loading the intended vite.config.ts or vitest.config.ts.
• Alias order: Vite resolves aliases in order, so overlapping entries can capture a more specific import unexpectedly.
• Import kind: a JavaScript import, CSS url(), asset URL, and Node-side require() do not all use the same resolution path.

Use the failing command directly so its config is visible:

1
pnpm exec vite --debug
2
pnpm exec vitest --run

If the message is wrapped in Vite’s optimized-dependency error, the Vite cache troubleshooting guide explains when vite --force is useful. Rebuilding that cache cannot repair a missing alias or a file with the wrong case. Likewise, if the problem appears only after deployment, compare it with the Vite production environment guide instead of changing the dev resolver.

Verify the same import in every tool#

After changing the mapping, test the exact boundary that failed:

1
pnpm exec vite --host 127.0.0.1
2
pnpm exec vitest --run
3
pnpm build

Open a route that imports the aliased module, run one test that imports the same path, and complete a production build. The fix is complete only when the editor, test runner, dev server, and build all agree on the target.

The durable rule is simple: tsconfig.paths describes TypeScript lookup, while Vite and Vitest need their own resolver behavior. Keep one authoritative target, use an absolute filesystem alias when configuring it explicitly, and verify from the package root that actually runs the command.

FAQ#