{"id":15556,"library":"bun-plugin-auto-imports","title":"Bun Auto-Imports Plugin","description":"bun-plugin-auto-imports is a utility plugin designed for the Bun bundler, enabling automatic import resolution and injection into JavaScript and TypeScript files during the build process. It streamlines development by reducing the need for explicit import statements, similar to features found in other build tools like Vite or Webpack's auto-imports plugins. The package is currently at version 0.4.0, indicating it is still in active development, with frequent minor releases and bug fixes as seen in recent changelogs. Its primary differentiator is its native integration with the Bun ecosystem, offering potentially faster build times compared to non-Bun specific solutions. It supports features like specifying directories for auto-import detection and ESLint integration. This plugin is crucial for projects leveraging Bun that seek to enhance developer experience and reduce boilerplate code.","status":"active","version":"0.4.0","language":"javascript","source_language":"en","source_url":"https://github.com/stacksjs/bun-plugin-auto-imports","tags":["javascript","auto-imports","bun","plugin","package","stacks","typescript"],"install":[{"cmd":"npm install bun-plugin-auto-imports","lang":"bash","label":"npm"},{"cmd":"yarn add bun-plugin-auto-imports","lang":"bash","label":"yarn"},{"cmd":"pnpm add bun-plugin-auto-imports","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"The plugin function is exported as a named export `autoImports`, not a default export.","wrong":"import autoImports from 'bun-plugin-auto-imports';","symbol":"autoImports","correct":"import { autoImports } from 'bun-plugin-auto-imports';"},{"note":"Import the TypeScript type definition for configuring the plugin.","symbol":"AutoImportsOptions","correct":"import type { AutoImportsOptions } from 'bun-plugin-auto-imports';"},{"note":"Bun plugins are registered via `Bun.plugin()` or the `plugins` array in `Bun.build()`. The `BunPlugin` type is for type declarations, not direct import as a function.","wrong":"import { BunPlugin } from 'bun';","symbol":"plugin","correct":"import { plugin } from 'bun';"}],"quickstart":{"code":"import { plugin } from 'bun';\nimport { autoImports } from 'bun-plugin-auto-imports';\nimport type { AutoImportsOptions } from 'bun-plugin-auto-imports';\n\nconst options: AutoImportsOptions = {\n  // Directories to scan for auto-importable modules\n  dirs: [\n    './src/composables',\n    './src/utils',\n  ],\n  // Optional: Explicitly define global imports (e.g., from npm packages)\n  imports: [\n    { name: 'z', from: 'zod' }, // Auto-import 'z' from 'zod'\n    { name: 'cn', from: 'classnames' }, // Auto-import 'cn' from 'classnames'\n  ],\n  // Generate a TypeScript declaration file for auto-imports\n  dts: './auto-imports.d.ts',\n  // Enable ESLint integration (as noted in features)\n  eslint: {\n    enabled: true,\n    filepath: './.eslintrc-auto-imports.json',\n  },\n};\n\n// Register the plugin globally for runtime or bundler usage\nplugin(autoImports(options));\n\n// Example source file: src/utils/formatters.ts\nexport function formatCurrency(amount: number) {\n  return `$${amount.toFixed(2)}`;\n}\n\n// Example source file: src/app.ts\n// In src/app.ts, you can now use formatCurrency without an explicit import:\n// console.log('Starting application...');\n// const price = 123.456;\n// console.log(`Formatted price: ${formatCurrency(price)}`);\n\n// To build with this plugin configuration (e.g., in bun.config.ts for build command):\n// export default {\n//   plugins: [\n//     autoImports(options)\n//   ],\n// };\n\nconsole.log('Bun auto-imports plugin configured. Check auto-imports.d.ts for types.');","lang":"typescript","description":"This quickstart demonstrates how to configure `bun-plugin-auto-imports` in your Bun environment, specifying directories to scan, explicit imports, and generating TypeScript declaration files. It shows the plugin registration using `plugin()` and an example of its options."},"warnings":[{"fix":"Pin the package version in `package.json` (e.g., `\"bun-plugin-auto-imports\": \"0.4.0\"`) and thoroughly test updates.","message":"As a pre-1.0 package, `bun-plugin-auto-imports` may introduce breaking changes in minor versions (e.g., from 0.3.x to 0.4.x) without adhering to strict semver. Always pin to exact versions or review changelogs carefully.","severity":"breaking","affected_versions":">=0.x.x"},{"fix":"Use specific `dirs` configurations, and explicitly define `imports` where clarity is needed. Leverage the generated `d.ts` file for type hinting to understand available globals.","message":"Auto-importing symbols can lead to naming conflicts, especially with generic names or when different modules export the same symbol. This can result in unexpected behavior or errors.","severity":"gotcha","affected_versions":">=0.1.0"},{"fix":"Ensure you are on `v0.3.1` or newer. Test path configurations thoroughly, especially when deploying to different environments. Use absolute paths where ambiguity is a concern.","message":"Path resolution within Bun plugins can sometimes be tricky or behave unexpectedly, especially in complex project structures or across different operating systems. A bug fix in `v0.3.1` specifically addressed issues with relative paths.","severity":"gotcha","affected_versions":"<0.3.1"},{"fix":"Regularly check the Bun and plugin repositories for updates and known issues. Report any new compatibility problems encountered.","message":"Bun's plugin API and its ecosystem are still evolving rapidly. Plugins might encounter compatibility issues with newer Bun versions or exhibit unexpected behavior due to changes in Bun's internal bundler or runtime.","severity":"gotcha","affected_versions":">=0.1.0"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"fix":"Verify that the file containing the desired symbol is within one of the `dirs` specified in the plugin options. Ensure the symbol is a valid export (e.g., `export function myFunction() {}`). Consider adding it to the `imports` option explicitly if it's a third-party package.","cause":"An auto-imported symbol was used but not correctly detected by the plugin. This often means the file containing the symbol is not within the configured `dirs` or the export pattern is not recognized.","error":"ReferenceError: [symbol] is not defined"},{"fix":"Explicitly define the import in the `imports` option of the plugin, specifying the exact named export. Ensure the source package's `package.json` correctly defines its `exports` field for proper module resolution.","cause":"Despite appearing to be auto-imported, Bun's bundler might not correctly resolve the named export from the underlying module, possibly due to CJS/ESM interop issues or incorrect export mapping.","error":"SyntaxError: Import named '[symbol]' not found in module '[path]'"},{"fix":"Ensure you are using `import { autoImports } from 'bun-plugin-auto-imports';` and passing its result directly to `plugin()` or the `plugins` array in `Bun.build()`. Verify the options object conforms to `AutoImportsOptions`.","cause":"The `bun-plugin-auto-imports` plugin was not correctly integrated into the Bun build or runtime process. This might be due to an incorrect import or improper function call.","error":"error: Plugin returned an invalid object"},{"fix":"Refactor your code to avoid naming conflicts. Use the `exclude` option in `AutoImportsOptions` (if available in this plugin, it's common in `unimport`-based plugins) to prevent specific symbols from being auto-imported, or prefix your auto-imported symbols to ensure uniqueness.","cause":"A symbol being auto-imported conflicts with a locally declared variable or another auto-imported symbol.","error":"Error: Duplicate identifier '[symbol]'"}],"ecosystem":"npm"}