esbuild-plugin-import-folder

1.0.1 verified Fri May 01 auth: no javascript

An esbuild plugin that enables importing all files from a folder dynamically, treating them as if they were imported individually. This plugin is at version 1.0.1, stable, and ships TypeScript types. It simplifies bulk imports for esbuild-based projects, offering a declarative way to include multiple files from a directory without manual import statements. Unlike similar solutions that rely on glob patterns or require resolution, this plugin integrates directly with esbuild's build process. It supports only ESM projects and requires esbuild >= 0.17.0. Use cases include loading all components, assets, or modules in a directory with a single import statement.

Common errors

error Error: [esbuild-plugin-import-folder] Expected a directory path, got undefined ↓

cause Missing or invalid 'directory' option in plugin configuration.

fix

Ensure to pass a valid directory path in the options object: importFolderPlugin({ directory: './path/to/dir' })

error TypeError: importFolderPlugin is not a function ↓

cause Using CommonJS require() on an ESM-only package.

fix

Change to import statement: import importFolderPlugin from 'esbuild-plugin-import-folder'

error Error: Cannot find module 'esbuild-plugin-import-folder' ↓

cause Package not installed or incorrect import path.

fix

Install the package: npm install esbuild-plugin-import-folder

Warnings

gotcha Plugin only works with ESM projects; requires esbuild >= 0.17.0 and Node.js >= 16. ↓

fix Ensure project uses ESM ("type": "module" in package.json) and update esbuild to v0.17+.

gotcha The plugin calls all files inside the directory - use with caution for large directories as it can significantly increase bundle size. ↓

fix Be selective with the directory or use filter options if available.

breaking Version 1.0.0 introduced the plugin as a default export; older alpha versions may have used named exports. ↓

fix Update to 1.0.0+ and use default import or named 'importFolderPlugin'.

Install

npm install esbuild-plugin-import-folder

yarn add esbuild-plugin-import-folder

pnpm add esbuild-plugin-import-folder

Imports

importFolderPlugin

wrong

const importFolderPlugin = require('esbuild-plugin-import-folder')

correct

import importFolderPlugin from 'esbuild-plugin-import-folder'

ESM-only; CommonJS require() will throw an error.

plugin (as import { importFolderPlugin })

wrong

import { default as importFolderPlugin } from 'esbuild-plugin-import-folder'

correct

import { importFolderPlugin } from 'esbuild-plugin-import-folder'

The default export is the plugin function; named export also available.

type ImportFolderPluginOptions

wrong

import { ImportFolderPluginOptions } from 'esbuild-plugin-import-folder'

correct

import type { ImportFolderPluginOptions } from 'esbuild-plugin-import-folder'

Type-only import to avoid runtime side effects in TypeScript.

Quickstart

Demonstrates basic setup of esbuild-plugin-import-folder to import all files from a directory.

import esbuild from 'esbuild';
import importFolderPlugin from 'esbuild-plugin-import-folder';

await esbuild.build({
  entryPoints: ['src/index.ts'],
  bundle: true,
  outfile: 'dist/bundle.js',
  plugins: [
    importFolderPlugin({
      directory: './src/components',
      importStatement: "import * as Components from './$RELATIVEPATH'"
    })
  ]
});

// In src/components/index.ts, you can now use:
// import * as Components from './components';