Registry / web-framework / bun-plugin-auto-imports

bun-plugin-auto-imports

JSON →
library0.4.0jsnpmunverified

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.

npm install bun-plugin-auto-imports
INSTALL
IMPORT
SIG · BUN-PLUGIN-AUTO-IM
B
bun-plugin-auto-imports
web-frameworkjavascriptv0.4.0
Install
—
Import
—
Disk
—
Pass rate
0/ 6
Env Coverage0 / 6
glibc
18–22
musl
18–22
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
musl
node 18–226 runs
build_error
glibc
node 18–226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

autoImports
✓ import { autoImports } from 'bun-plugin-auto-imports';
✗ 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
✓ import { plugin } from 'bun';
✗ import { BunPlugin } 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.

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.');
Debug
Known issues
breakingAs 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.
affects: >=0.x.x
gotchaAuto-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.
affects: >=0.1.0
gotchaPath 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.
affects: <0.3.1
gotchaBun'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.
affects: >=0.1.0
Errors
Common errors & fixes
ReferenceError: [symbol] is not defined
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]'
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
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]'
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.
Upgrade
Version history
0.4.0latest on npm
Audit
Dependencies

No dependency data recorded yet.

Agent activity
5 hits · last 30 days
node
4
OpenAI (training)
1
Resources
bun-plugin-auto-imports — npm install bun-plugin-auto-imports · libregistry