esbuild-plugin-rawbundle

0.2.2 verified Fri May 01 auth: no javascript

esbuild plugin that allows importing modules as bundled ESM strings via the `?rawbundle` query suffix. Version 0.2.2 is the latest stable release. This plugin processes imports like `import raw from 'jquery?rawbundle'` and returns the esbuild-bundled output as a default string export, using the specified esbuild options. It is maintained for esbuild plugin ecosystem integration. Differentiators: built on top of esbuild's internal bundling, supports any format/platform, and provides raw bundled content for dynamic use cases like code injection or embedding.

Common errors

error Error: Cannot find module 'esbuild-plugin-rawbundle' ↓

cause Package not installed or incorrect import path.

fix

npm install --save-dev esbuild-plugin-rawbundle

error TypeError: rawBundlePlugin is not a function ↓

cause Using CommonJS require instead of ESM import.

fix

Use import rawBundlePlugin from 'esbuild-plugin-rawbundle' and ensure package.json has "type": "module".

error Error: The plugin 'rawbundle' does not have a valid setup callback ↓

cause Plugin object not correctly passed to esbuild's plugins array.

fix

Ensure plugins array contains the result of rawBundlePlugin(options), not a different object.

error Build failed with 1 error: error: No loader is configured for ".html" files ↓

cause Importing a file type not handled by esbuild's default loaders without proper esbuildOptions.

fix

Add appropriate loader to esbuildOptions, e.g., rawBundlePlugin({ esbuildOptions: { loader: { '.html': 'text' } } }).

Warnings

gotcha The plugin only processes imports ending with `?rawbundle`. Other imports are passed through unmodified. ↓

fix Ensure your imports use the `?rawbundle` suffix exactly.

gotcha If `esbuildOptions.write` is not set to false, esbuild may write output files unexpectedly. The plugin internally sets `write: false` but if you override it, files can be written to disk. ↓

fix Do not set `write: true` in esbuildOptions passed to the plugin.

deprecated No deprecation warnings known for this version. ↓

fix None.

gotcha The plugin requires esbuild as a peer dependency. Incompatible esbuild versions may cause runtime errors. ↓

fix Ensure esbuild is installed and version matches plugin requirements.

breaking No breaking changes known for current version. ↓

fix None.

Install

npm install esbuild-plugin-rawbundle

yarn add esbuild-plugin-rawbundle

pnpm add esbuild-plugin-rawbundle

Imports

default

wrong

const rawBundlePlugin = require('esbuild-plugin-rawbundle');

correct

import rawBundlePlugin from 'esbuild-plugin-rawbundle';

Package is ESM-only; CommonJS require will fail.

rawBundle

wrong

import { rawBundle } from 'jquery?rawbundle';

correct

import rawBundle from 'jquery?rawbundle'; // default export is a string

The ?rawbundle suffix triggers the plugin on a per-import basis.

rawBundlePlugin options

wrong

rawBundlePlugin(new esbuild.BuildOptions())

correct

rawBundlePlugin({ esbuildOptions: { format: 'esm', platform: 'browser' } })

esbuildOptions are a plain object, not an esbuild BuildOptions instance.

Quickstart

Demonstrates using esbuild-plugin-rawbundle to bundle a dependency as a raw string import via the ?rawbundle query.

import rawBundlePlugin from 'esbuild-plugin-rawbundle';
import * as esbuild from 'esbuild';

await esbuild.build({
  entryPoints: ['src/index.js'],
  bundle: true,
  outfile: 'out.js',
  plugins: [
    rawBundlePlugin({
      esbuildOptions: {
        format: 'esm',
        platform: 'browser',
        write: false,
      },
    }),
  ],
});

// In src/index.js:
// import myBundle from './lib?rawbundle';
// console.log(myBundle); // string of bundled content