esbuild-raw-plugin

0.3.1 verified Fri May 01 auth: no javascript

A lightweight ESBuild and TSUP plugin (v0.3.1) that allows importing any file as raw text, base64, data URL, binary, or file content with zero configuration. Supports query suffixes like `?raw`, `?text`, `?base64`, `?dataurl`, `?binary`, `?file`, and automatically resolves file extensions. Useful for loading code files in documentation, interactive demos with react-live, or template-driven workflows. Actively maintained with monthly releases on npm, ships TypeScript types, and integrates seamlessly with ESBuild and TSUP builds.

Common errors

error Error: No loader is configured for ".raw" files ↓

cause esbuild does not natively handle `.raw` extensions; the query suffix `?raw` may not be stripped before looking up a loader.

fix

Ensure the plugin is correctly listed in plugins array and that you've imported raw properly.

error Cannot find module './example.ts?raw' or its corresponding type declarations. ↓

cause TypeScript cannot resolve the query-suffixed import without a module declaration.

fix

Add declare module '*?raw' { const content: string; export default content; } to a .d.ts file.

error TypeError: raw is not a function ↓

cause Importing the default export incorrectly when using CommonJS require.

fix

Use const { raw } = require('esbuild-raw-plugin'); or import { raw } from 'esbuild-raw-plugin';.

error Error: Build failed with 1 error: error: Unexpected "?" ↓

cause esbuild version < 0.8 does not support query strings in import paths.

fix

Update esbuild to >=0.8.0 and ensure you're using a compatible version.

Warnings

breaking Binary loaders were fixed in v0.3.0 — upgrades from earlier versions may change behavior for base64/dataurl/binary imports. ↓

fix Update to >=0.3.0: npm install esbuild-raw-plugin@latest

deprecated The `ext` option (array of extensions) still works but the plugin no longer requires it; it now falls back to all known extensions. Old usage of `ext` may be redundant. ↓

fix Remove `ext` if you rely on default extension resolution, or keep for explicit control.

gotcha The plugin uses a regex-based onLoad filter — it may not intercept imports that have already been handled by other plugins with higher priority. Ensure your plugin order in the array is correct. ↓

fix Place `raw()` before other esbuild plugins in the plugins array.

gotcha For TypeScript projects, you must add a module declaration for `*?raw` and other query suffixes to avoid type errors. ↓

fix Add to declarations.d.ts: `declare module '*?raw' { const content: string; export default content; }`

gotcha The plugin resolves filenames without extensions by trying multiple extensions — this can cause unexpected file resolution if multiple files with same name but different extensions exist in the same directory. ↓

fix Specify full filename with extension to avoid ambiguity: import code from './file.ts?raw' instead of './file?raw'.

Install

npm install esbuild-raw-loader

yarn add esbuild-raw-loader

pnpm add esbuild-raw-loader

Imports

raw
```
import { raw } from 'esbuild-raw-plugin'
```
Named export; the plugin is ESM-only. CommonJS require('esbuild-raw-plugin').raw also works.
default
```
import raw from 'esbuild-raw-plugin'
```
Default import is supported as an alias to the named export.
RawPluginOptions
```
import { RawPluginOptions } from 'esbuild-raw-plugin'
```
TypeScript type export for configuring plugin options.

Quickstart

Demonstrates how to use the plugin with ESBuild, import files with query suffixes, and configure custom loaders.

import { build } from 'esbuild';
import { raw } from 'esbuild-raw-plugin';

await build({
  entryPoints: ['src/index.js'],
  bundle: true,
  outfile: 'out.js',
  plugins: [raw({
    loader: 'text',
    ext: ['.ts', '.tsx', '.js', '.css', '.md'],
    customLoaders: { '.scss': 'text', '.png': 'dataurl' }
  })],
});

// In your source code:
import code from './example.ts?raw';
console.log(code); // raw text of example.ts
import img from './image.png?base64';
console.log(img); // base64-encoded image data URL