unplugin-auto-import

unplugin-auto-import scans your code and injects the import statements for framework composables and utilities on demand, so ref, computed, useState, or any custom module export is available globally without writing an import line. It works by transforming source files at build time through the unplugin abstraction layer, which means the same plugin logic runs unmodified across Vite, Webpack, Rollup, Rolldown, Rspack, and esbuild.

Under the hood it delegates the actual import-scanning and injection to unimport, the lower-level engine originally built for Nuxt’s auto-import feature; this package wraps that engine with a friendlier configuration surface, built-in presets for popular libraries (Vue, React, Svelte, Solid, Preact, Pinia, Vuex, VueUse, and more), directory-based auto-imports, custom resolvers compatible with unplugin-vue-components, and generated .d.ts/ESLint/Biome config files so TypeScript and linters stay aware of the injected globals.

It is best understood as a build-time code transform tool rather than a runtime library — projects add it to their bundler config once, and it then rewrites application source on every build, never shipping any of its own code into the output bundle.

What You Get

• A single plugin API that works identically across Vite, Webpack, Rollup, Rolldown, Rspack, esbuild, and Astro via bundler-specific entry points (/vite, /webpack, /rollup, /rolldown, /rspack, /esbuild, /astro)
• Built-in import presets for popular ecosystems: Vue, Vue Router, Pinia, Vuex, React, React Router, Preact, Solid, Svelte, Jotai, Recoil, MobX, ahooks, VueUse, Quasar, and more
• Directory-based auto-import (dirs option) that scans folders like ./composables or ./hooks and registers every module export as a global import
• Automatic .d.ts type-declaration generation so TypeScript recognizes auto-imported identifiers with no manual ambient declarations
• Generated ESLint (.eslintrc-auto-import.json) and Biome lint config output so no-undef doesn’t flag injected globals
• Custom resolver support compatible with unplugin-vue-components, letting on-demand component or directive resolution plug into the same import pipeline

Common Use Cases

• Vue 3 or Nuxt-style projects that want ref, computed, watch, and VueUse composables available everywhere without repetitive import boilerplate
• React codebases standardizing on auto-imported hooks like useState and useEffect to cut down import noise across many small components
• Design-system or component libraries exposing local composables/hooks under a composables/ or hooks/ directory that should be globally available via the dirs scanning option
• Teams migrating a bundler (e.g. Webpack to Vite, or to Rolldown) that want auto-import behavior to keep working unchanged because the plugin is unplugin-based
• Projects that need generated ESLint globals config so CI linting doesn’t fail on identifiers injected by the auto-import transform

Under The Hood

Architecture The plugin entry point (src/core/unplugin.ts) is a thin createUnplugin wrapper: it wires bundler-specific hooks (transformInclude, transform, buildStart/buildEnd, plus Vite-only config/handleHotUpdate/configResolved) around a single stateful ctx object created by createContext in src/core/ctx.ts. That context owns an unimport instance, the resolved import list, and the throttled config-file writer, and is recreated whenever Vite’s resolved root changes. Transform is a two-step pipeline: ctx.filter(id) decides whether a file is in scope using an include/exclude regex filter, then ctx.transform hands the source to unimport.injectImports via a MagicString buffer so edits stay source-mapped. Directory-based imports flow through a separate scanDirs path that merges dynamic directory exports with static imports on every rescan. Swapping the core import-resolution engine would mean replacing the unimport dependency entirely, since virtually all matching, presets, and dts generation is delegated to it rather than implemented locally.

Tech Stack Written in TypeScript, targeting Node >=20.19, built with tsdown (multi-entry esbuild-based bundler configured in tsdown.config.ts to emit per-bundler-target files under dist/) and type-checked with tsgo (TypeScript’s native-preview compiler). The runtime dependency surface is small and deliberate: unimport for import scanning/injection, unplugin and unplugin-utils for cross-bundler plugin definition and filtering, magic-string for source transforms, local-pkg for detecting installed packages, and picomatch for directory glob matching. Peer dependencies (@nuxt/kit, @vueuse/core) are optional and only exercised by specific presets/entry points. Test tooling is vitest with tinyglobby for fixture globbing, and linting runs through @antfu/eslint-config.

Code Quality Tests live under test/ (transform.test.ts, dts.test.ts, search.test.ts, biomelintrc.test.ts) with snapshot fixtures in test/fixtures* covering presets, custom import maps, ignore lists, and generated .d.ts/lint-config output — a substantial functional test suite exercising the transform pipeline end-to-end rather than isolated unit stubs. Error handling favors early warnings over thrown exceptions (e.g. a console warning when no imports/resolvers/dirs are configured) rather than typed error objects. Naming is consistent and descriptive (createContext, scanDirs, writeConfigFilesThrottled), types are defined centrally in src/types.ts with explicit @deprecated JSDoc annotations tracking API evolution, and CI (.github/workflows/unit-test.yml) runs the test suite plus a separate release workflow gated on tags — indicating an actively maintained, typed, and lint-enforced codebase.

API Design The public API is a single default export per bundler entry (/vite, /webpack, /rollup, /rolldown, /rspack, /esbuild, /astro, /nuxt) so switching build tools requires changing only the import path, not the options object — a deliberate ergonomic choice given how many bundlers unplugin targets. Options are extensively JSDoc-documented in src/types.ts with defaults noted inline, and the preset system lets consumers opt into common frameworks ('vue', 'react', etc.) with a single string rather than hand-writing import maps. The resolver interface intentionally mirrors unplugin-vue-components’s resolver contract, letting the ecosystem share resolver implementations across both plugins with zero adaptation code required from consumers.