vite-aliases

0.11.8 verified Mon Apr 27 auth: no javascript

Vite plugin for automatic alias generation based on folder structure. Current stable version is 0.11.8, requiring Vite 6.x (peer dependency). Release cadence is irregular with minor patches. Key differentiator: eliminates manual alias configuration by scanning src directory and creating aliases like @components, @utils automatically. Supports TypeScript, configurable depth, prefix, and duplicate handling. v0.11+ changed default prefix from @ to ~ and replaced useTypescript option with auto-detection. ESM-only; no CommonJS support.

Common errors

error TypeError: vite_aliases_1.ViteAliases is not a function ↓

cause Using default import instead of named import.

fix

Change to: import { ViteAliases } from 'vite-aliases'

error Error: Cannot find module 'vite-aliases' ↓

cause Missing installation or ESM configuration incorrect.

fix

Install with 'npm install vite-aliases -D' and ensure package.json has "type": "module"

error The 'ViteAliases' plugin is not compatible with Vite 5. ↓

cause Peer dependency requires Vite 6.x. Using older Vite versions fails.

fix

Upgrade Vite to version 6.x, or downgrade vite-aliases to an older version.

Warnings

breaking Default prefix changed from '@' to '~' in v0.11.1. Existing projects relying on '@' prefix will break. ↓

fix Explicitly set prefix: '@' in options to preserve old behavior.

deprecated Option 'useTypescript' was removed in v0.11.0; renamed to 'dts' with auto-detection. Using 'useTypescript' has no effect. ↓

fix Use 'dts: true' or rely on auto-detection.

breaking ESM-only since v0.10.0. The package no longer supports CommonJS require(). ↓

fix Add "type": "module" to package.json or use .mjs extension for config file.

gotcha Duplicate folder names cause an error unless 'adjustDuplicates' is enabled. ↓

fix Set adjustDuplicates: true to automatically generate camelCased aliases.

deprecated Logfile generation via 'createLog' and 'logPath' may be phased out in future releases; recommended to use Vite's built-in logging. ↓

fix Avoid relying on logfile output; monitor terminal output instead.

Install

npm install vite-aliases

yarn add vite-aliases

pnpm add vite-aliases

Imports

ViteAliases
wrong
```
const ViteAliases = require('vite-aliases')
```
correct
```
import { ViteAliases } from 'vite-aliases'
```
Package is ESM-only, require() will fail. Default export is not available.
ViteAliases (default import attempt)
wrong
```
import ViteAliases from 'vite-aliases'
```
correct
```
import { ViteAliases } from 'vite-aliases'
```
No default export; must use named import.
Plugin invocation
wrong
```
new ViteAliases()
```
correct
```
ViteAliases({ prefix: '@' })
```
ViteAliases is a function that returns a plugin object, not a class.

Quickstart

Shows a complete ViteAliases plugin configuration with all available options.

// vite.config.js
import { ViteAliases } from 'vite-aliases'

export default {
  plugins: [
    ViteAliases({
      dir: 'src',
      prefix: '~',
      deep: true,
      depth: 1,
      createLog: false,
      adjustDuplicates: false,
      useAbsolute: false,
      useIndexes: false,
      useConfig: true,
      dts: false,
      silent: false,
      root: process.cwd()
    })
  ]
}