Maaz Zindani

Loading the index…

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

The @ alias for src does not work in a Vite project

ErrorFailed to resolve import "@/components/Header.vue"

Short answer

Vite has no built in @ alias. Define it in resolve.alias with an absolute path, because a relative value is used as written and does not point at the file system. Then mirror it in tsconfig paths for the editor, or let Vite read the paths itself.

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

Fix it fast

  1. 1Find out which cause you have

    Search the config for an alias entry. If there is none, Vite does not know what @ means.

    grep -n -B2 -A6 alias vite.config.*
  2. 2Match what you see, then jump to its fix

    1. 1Failed to resolve import with a path that starts with @No alias is defined in the Vite configFix
    2. 2The alias exists, but files are still not foundThe alias target is a relative pathFix
    3. 3The editor resolves @, but vite build or dev does nottsconfig paths are not applied by ViteFix

What does the error look like?

  • Failed to resolve import "@/components/Header.vue"
  • Imports with @ work in the editor but fail in the browser
  • The alias worked in Vue CLI and webpack but not after moving to Vite

Cause 1 of 3

No alias is defined in the Vite config

1Check

Vue CLI and webpack gave you @ by default. Vite does not, so the config must define it.

grep -n alias vite.config.*

2Fix

Add resolve.alias that maps @ to the src folder.

import { resolve } from 'node:path'
import { defineConfig } from 'vite'

export default defineConfig({
  resolve: {
    alias: {
      '@': resolve(import.meta.dirname, 'src'),
    },
  },
})

3Verify

Restart the dev server and open a page that uses an @ import.

npm run dev

Confirmed by vite.dev

Did this fix it?

Cause 2 of 3

The alias target is a relative path

1Check

When aliasing to file system paths, always use absolute paths. A relative value such as ./src is used as written and is not resolved to a file system path.

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

2Fix

Build the absolute path with resolve, as in the snippet above, instead of writing ./src.

'@': resolve(import.meta.dirname, 'src')

3Verify

Restart Vite and import a file through @.

npm run dev

Confirmed by vite.dev

Did this fix it?

Cause 3 of 3

tsconfig paths are not applied by Vite

1Check

tsconfig paths only help TypeScript. Vite uses them only when told to, and then only for files matched by the tsconfig files or include.

grep -n -A3 paths tsconfig*.json

2Fix

Keep one source of truth: either the Vite alias above plus matching tsconfig paths, or switch on resolve.tsconfigPaths in Vite versions that offer it.

// vite.config.ts
export default defineConfig({
  resolve: { tsconfigPaths: true },
})

3Verify

Run a production build, which exercises every import.

npm run build

Confirmed by vite.dev

Did this fix it?

How do I stop it coming back?

  • Define each alias once and copy it to tsconfig paths in the same commit.
  • Use absolute paths for every alias target.
  • Run a production build in CI so a broken alias is caught early.

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.