Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
default
✓ import AutoImport from 'unplugin-auto-import/vite'
✗ const AutoImport = require('unplugin-auto-import/vite')
E5-only since v21; use dynamic import in CommonJS or upgrade to ESM.
default
✓ import AutoImport from 'unplugin-auto-import/webpack'
✗ const AutoImport = require('unplugin-auto-import/webpack')
For Webpack/Rspack config files written in CommonJS, use dynamic import or switch to ESM.
default
✓ import AutoImport from 'unplugin-auto-import/rollup'
✗ import AutoImport from 'unplugin-auto-import'
Must import from subpath for the specific bundler; default export from root is not available.
Shows basic Vite + Vue setup with auto-import plugin, enabling Vue composables without explicit imports.
// vite.config.ts (ESM)
import { defineConfig } from 'vite'
import AutoImport from 'unplugin-auto-import/vite'
export default defineConfig({
plugins: [
AutoImport({
imports: ['vue', 'vue-router'],
dts: true // or './src/types/auto-imports.d.ts'
})
]
})
// Now use ref, computed, etc. without imports:
import { ref, computed } from 'vue' // not needed
const count = ref(0)
const doubled = computed(() => count.value * 2)
Debug
Known issues
breakingv21.0.0 dropped CommonJS support (ESM-only) and requires Node >=20.19.0fixEnsure project is ESM (type: module in package.json or .mjs files) and upgrade Node to >=20.19.0.
affects: >=21.0.0
breakingv20.0.0 requires @nuxt/kit v4; incompatible with @nuxt/kit v3fixUpdate @nuxt/kit to ^4.0.0 if using Nuxt integration.
affects: >=20.0.0 <21.0.0
deprecatedOption 'dts' default value changed; v19+ no longer generates dts by defaultfixSet dts: true explicitly in options to generate TypeScript declarations.
affects: >=19.0.0
gotchaAuto-import only works in files matching include patterns; TypeScript may report missing types if dts not generated or imported.fixEnsure files are in 'include' glob and set 'dts: true' or manually reference generated types via tsconfig.json include.
affects: >=0.0.0
Errors
Common errors & fixes
Cannot find module 'unplugin-auto-import/vite' or its corresponding type declarations.
Node.js <20.19.0 or CommonJS environment without dynamic import.
fixUpgrade Node to >=20.19.0 and ensure project type is 'module' in package.json, or use dynamic import: const AutoImport = await import('unplugin-auto-import/vite').then(m => m.default); Error: [unplugin-auto-import] Failed to resolve preset: 'vue'
Missing Vue dependency; auto-import presets require the corresponding library installed.
fixInstall the library: npm install vue (or react, etc.)
TypeScript error: 'ref' is not defined
Type declarations not generated or not included in tsconfig.
fixSet 'dts: true' in AutoImport options and ensure generated dts file (e.g., 'auto-imports.d.ts') is included in tsconfig.json's 'include' array.
Audit
Dependencies
@nuxt/kitoptionalPeer dependency for Nuxt integration (required for Nuxt preset).
@vueuse/coreoptionalPeer dependency for VueUse preset (optional but commonly used).