esbuild-plugin-autoload

0.3.3 verified Fri May 01 auth: no javascript

esbuild/Bun plugin that resolves autoload patterns at build time, supporting @gramio/autoload and elysia-autoload. Version 0.3.3 (stable), requires Bun >=1.1 or Node >=22. It scans a directory for files matching a glob pattern and generates import statements so that autoload-capable libraries can find them at runtime. Unlike generic glob plugins, this one specifically patches the import resolution for elysia-autoload and @gramio/autoload, making it useful for Elysia.js and Gramio projects that rely on convention-based file loading.

Common errors

error Error: The plugin "esbuild-plugin-autoload" must be run with at least Node v22 or Bun v1.1 ↓

cause Runtime version too low; Glob API requires Node >=22 or Bun >=1.1.

fix

Upgrade Node to >=22 or Bun to >=1.1.

error TypeError: autoload is not a function ↓

cause Default import used incorrectly with named export expectations.

fix

Use default import: import autoload from 'esbuild-plugin-autoload'.

error ReferenceError: require is not defined in ES module scope ↓

cause Using CommonJS require() in an ESM project.

fix

Use import syntax: import { autoload } from 'esbuild-plugin-autoload'.

Warnings

breaking Requires Bun >=1.1 or Node >=22 for Glob support; older runtimes will throw. ↓

fix Upgrade to Bun 1.1+ or Node 22+. Alternatively, use v0.2.x if locked to older runtimes.

gotcha Bun compile mode does not support runtime autoload without an extra build step; see the Bun issue. ↓

fix Bundle with Bun.build first, then compile the output with `bun build --compile out/index.js`.

gotcha Only supports elysia-autoload and @gramio/autoload; other autoload libraries will not work. ↓

fix Check your autoload library against the supported list. Open an issue to request new ones.

deprecated Default import and named import are both allowed; no deprecation yet, but prefer named import for consistency. ↓

fix Use `import { autoload }` instead of `import autoload`.

Install

npm install esbuild-plugin-autoload

yarn add esbuild-plugin-autoload

pnpm add esbuild-plugin-autoload

Imports

autoload

wrong

const autoload = require('esbuild-plugin-autoload')

correct

import { autoload } from 'esbuild-plugin-autoload'

ESM-only; requires Node >=22 or Bun >=1.1

autoload as default

wrong

import { autoload } from 'esbuild-plugin-autoload'

correct

import autoload from 'esbuild-plugin-autoload'

Both named and default imports are supported and equivalent.

type AutoloadOptions

import type { AutoloadOptions } from 'esbuild-plugin-autoload'

TypeScript type exported for options object.

Quickstart

Minimal esbuild setup with autoload plugin to scan './src/routes' for files and generate import statements at build time.

import { autoload } from 'esbuild-plugin-autoload'
import esbuild from 'esbuild'

await esbuild.build({
  entryPoints: ['src/index.ts'],
  outdir: 'dist',
  bundle: true,
  plugins: [
    autoload({
      pattern: '**/*.{ts,tsx,js}',
      directory: './src/routes',
      debug: process.env.DEBUG === '1'
    })
  ]
})

console.log('Build complete')