Bun Auto-Imports Plugin

Common errors

• ReferenceError: [symbol] is not defined

  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.
  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.

• SyntaxError: Import named '[symbol]' not found in module '[path]'

  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.
  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.

• error: Plugin returned an invalid object

  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.
  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`.

• Error: Duplicate identifier '[symbol]'

  cause A symbol being auto-imported conflicts with a locally declared variable or another auto-imported symbol.
  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.

Warnings

• breaking 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.
  Fix: Pin the package version in `package.json` (e.g., `"bun-plugin-auto-imports": "0.4.0"`) and thoroughly test updates.
• gotcha 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.
  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.
• gotcha 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.
  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.
• gotcha 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.
  Fix: Regularly check the Bun and plugin repositories for updates and known issues. Report any new compatibility problems encountered.

Install

• npm install bun-plugin-auto-imports npm
• yarn add bun-plugin-auto-imports yarn
• pnpm add bun-plugin-auto-imports pnpm

Imports

• autoImports
  wrong:

  import autoImports from 'bun-plugin-auto-imports';

  correct:

  import { autoImports } from 'bun-plugin-auto-imports';

  The plugin function is exported as a named export `autoImports`, not a default export.
• AutoImportsOptions

  import type { AutoImportsOptions } from 'bun-plugin-auto-imports';

  Import the TypeScript type definition for configuring the plugin.
• plugin
  wrong:

  import { BunPlugin } from 'bun';

  correct:

  import { plugin } from 'bun';

  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.

Quickstart

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.

import { plugin } from 'bun';
import { autoImports } from 'bun-plugin-auto-imports';
import type { AutoImportsOptions } from 'bun-plugin-auto-imports';

const options: AutoImportsOptions = {
  // Directories to scan for auto-importable modules
  dirs: [
    './src/composables',
    './src/utils',
  ],
  // Optional: Explicitly define global imports (e.g., from npm packages)
  imports: [
    { name: 'z', from: 'zod' }, // Auto-import 'z' from 'zod'
    { name: 'cn', from: 'classnames' }, // Auto-import 'cn' from 'classnames'
  ],
  // Generate a TypeScript declaration file for auto-imports
  dts: './auto-imports.d.ts',
  // Enable ESLint integration (as noted in features)
  eslint: {
    enabled: true,
    filepath: './.eslintrc-auto-imports.json',
  },
};

// Register the plugin globally for runtime or bundler usage
plugin(autoImports(options));

// Example source file: src/utils/formatters.ts
export function formatCurrency(amount: number) {
  return `$${amount.toFixed(2)}`;
}

// Example source file: src/app.ts
// In src/app.ts, you can now use formatCurrency without an explicit import:
// console.log('Starting application...');
// const price = 123.456;
// console.log(`Formatted price: ${formatCurrency(price)}`);

// To build with this plugin configuration (e.g., in bun.config.ts for build command):
// export default {
//   plugins: [
//     autoImports(options)
//   ],
// };

console.log('Bun auto-imports plugin configured. Check auto-imports.d.ts for types.');