Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Next.js and React

The @/ import path does not resolve in Vite, Vitest or the editor

ErrorFailed to resolve import "@/components/Header.vue" from "src/App.vue". Does the file exist?

Short answer

Vite does not know what @ means until you define it in resolve.alias, with an absolute path. A tsconfig paths entry only helps the type checker. Vitest reads the alias from your Vite config, but a separate vitest.config file replaces that config unless you merge them.

  • Applies to Vite 7, Vitest 3, TypeScript 5.x, Node.js 22
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Find out where the alias is (or is not) defined: the Vite config, a separate Vitest config, and tsconfig.

    ls vite.config.* vitest.config.* tsconfig*.json
    grep -n "alias" vite.config.* vitest.config.* 2>/dev/null
  2. 2Match what you see, then jump to its fix

    1. 1Failed to resolve import "@/..." in the dev server or the buildNo alias is defined in the Vite configFix
    2. 2The alias exists but the import still fails, often with a path like ./src in the messageThe alias path is relative, so Vite uses it as writtenFix
    3. 3The app builds, but only the tests fail with Failed to resolve import "@/..."A separate vitest.config file replaced the Vite configFix
    4. 4The editor accepts @/ imports, the bundler does nottsconfig paths is set, but Vite is not told to use itFix

What does the error look like?

  • Failed to resolve import "@/components/Header.vue" from "src/App.vue". Does the file exist?
  • Failed to resolve import "@/utils" from "src/utils.test.ts". Does the file exist?

Cause 1 of 4

No alias is defined in the Vite config

1Check

Open vite.config and look for resolve.alias. A tsconfig paths entry alone does not count, because Vite does not read it by default.

grep -n -A4 "resolve" vite.config.*

2Fix

Add the alias to the Vite config. Aliases that point at the file system need an absolute path, so build one from the config file's own location.

// vite.config.ts
import { defineConfig } from 'vite'
import { fileURLToPath, URL } from 'node:url'

export default defineConfig({
  resolve: {
    alias: {
      '@': fileURLToPath(new URL('./src', import.meta.url)),
    },
  },
})

3Verify

Restart the dev server and open a page that imports through the alias.

npx vite build

Confirmed by vite.dev

Did this fix it?

Cause 2 of 4

The alias path is relative, so Vite uses it as written

1Check

Look at the right-hand side of the alias. A value such as './src' or '/src' is not turned into a file system path.

grep -n "'@'" vite.config.*

2Fix

Replace the relative value with an absolute one, as in the example above.

alias: {
  '@': fileURLToPath(new URL('./src', import.meta.url)),
}

3Verify

Run the build again and confirm the error is gone.

npx vite build

Confirmed by vite.dev

Did this fix it?

Cause 3 of 4

A separate vitest.config file replaced the Vite config

1Check

When both vite.config and vitest.config exist, Vitest uses the second one and ignores the first, so the alias never reaches the tests.

ls vite.config.* vitest.config.*

2Fix

Merge the Vite config into the Vitest config, or move the test options into vite.config under a test key and delete the second file.

// vitest.config.ts
import { defineConfig, mergeConfig } from 'vitest/config'
import viteConfig from './vite.config'

export default mergeConfig(viteConfig, defineConfig({
  test: { environment: 'jsdom' },
}))

3Verify

Run the tests once.

npx vitest run

Confirmed by vitest.dev

Did this fix it?

Cause 4 of 4

tsconfig paths is set, but Vite is not told to use it

1Check

TypeScript paths only tells the type checker how to resolve an import. It does not change what runs, so another tool must provide the same mapping.

grep -n -B1 -A3 "paths" tsconfig*.json

2Fix

Keep the mapping in both places: the alias in the Vite config, and the matching paths entry in tsconfig so the editor and tsc agree.

// tsconfig.json (compilerOptions)
"paths": { "@/*": ["./src/*"] }

3Verify

Run the type check and the build.

npx tsc --noEmit
npx vite build

Confirmed by typescriptlang.org

Did this fix it?

How do I stop it coming back?

  • Define the alias once in the Vite config and mirror it in tsconfig paths in the same commit.
  • Keep one config file for Vite and Vitest, or use mergeConfig, so the two never drift.
  • Use an absolute path for every alias that points into the project.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Projects of mine built on the same technologies:

Related fixes

Web apps

tsconfig rejects allowImportingTsExtensions

An error that allowImportingTsExtensions needs noEmit or emitDeclarationOnly

allowImportingTsExtensions lets files import each other with .ts or .tsx extensions, and TypeScript only allows it together with noEmit or emitDeclarationOnly.

2 causes, each with a fix

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.