The @ alias for src does not work in a Vite project
Failed 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.
Fix it fast
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.*2Match what you see, then jump to its fix
What does the error look like?
Failed to resolve import "@/components/Header.vue"Imports with @ work in the editor but fail in the browserThe 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 devConfirmed by vite.dev
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 devConfirmed by vite.dev
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*.json2Fix
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 buildConfirmed by vite.dev
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:
- TaxiDexMy own multi-tenant taxi dispatch SaaS: API, dispatcher portal, driver and passenger apps, and the servers underneath.
- QistLockA NestJS and React SaaS driving an Android Device Owner agent that locks financed phones when payments lapse.
- WorkforceA field app, an admin console and a self-hosted Node.js server for push and reconciliation.
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 fixWeb apps
Cypress refuses to start with 'Your configFile is invalid'
Your configFile threw an error from: /path/to/cypress.config.ts
Cypress could not load cypress.config.js or .ts, or found something wrong in it.
5 causes, each with a fixWeb apps
ESLint cannot decide which copy of the @typescript-eslint plugin to use
The message lists two file paths for the same plugin, each with the name of the config that loaded it
ESLint found the same plugin at two different file paths and will not pick one.
3 causes, each with a fixWeb apps
ESLint says it cannot resolve a path to a module that does exist
Unable to resolve path to module 'react'. import/no-unresolved
import/no-unresolved fails when eslint-plugin-import cannot find the file or package on disk with its resolver.
4 causes, each with a fixWeb apps
ESLint was configured to run using parserOptions.project, but the file is not in the TSConfig
However, that TSConfig does not include this file
Type-aware linting needs every linted file to belong to a TypeScript project.
4 causes, each with a fixWeb apps
Upgrading to Next.js 16: middleware becomes proxy, and the other things that break
Missing Required default.js for Parallel Route
Next.js 16 renames middleware.ts to proxy.ts and its exported function to proxy.
6 causes, each with a fix