esbuild-raw-plugin

0.3.1 verified Fri May 01 auth: no javascript

An ESBuild and TSUP plugin that allows importing files as raw text, base64, binary, or data URLs with zero configuration. Version 0.3.1 is the latest stable release, with recent releases including backward-compatible fixes and binary loader improvements. Key differentiators: supports query suffixes like ?raw, ?text, ?base64, ?binary, ?dataurl, ?file; smart fallback extension resolution; custom loader mapping; regex-based native onLoad filter for performance; works with both ESBuild and TSUP. Developed under react18-tools, it is lightweight and targets documentation tools, live editors (react-live), markdown tooling, and template-driven workflows.

Common errors

error Cannot find module 'esbuild-raw-plugin' ↓

cause Missing install or using CommonJS require with an ESM-only package.

fix

Install the package: npm install esbuild-raw-plugin --save-dev and use ES module imports (e.g., import { raw } from 'esbuild-raw-plugin').

error Module '"*.ts?raw"' has no exported member 'default'. ↓

cause TypeScript cannot find type declarations for raw imports.

fix

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

error Error: The plugin 'raw' must be an object with a 'name' property, or a function returning one. ↓

cause Incorrect usage of the plugin (e.g., passing raw directly without calling raw()).

fix

Call the function: plugins: [raw()] instead of plugins: [raw].

error The requested module 'esbuild-raw-plugin' does not provide an export named 'default' ↓

cause Using default import but the package no longer exports a default export in newer versions.

fix

Use named import: import { raw } from 'esbuild-raw-plugin'.

Warnings

breaking Binary loaders fixed in v0.3.0: earlier versions may not correctly resolve binary file imports. ↓

fix Upgrade to >=0.3.0 for proper binary loader support.

deprecated Default export 'rawDefault' is deprecated since v0.2.0: use named export 'raw' instead. ↓

fix Replace `import raw from 'esbuild-raw-plugin'` with `import { raw } from 'esbuild-raw-plugin'`.

gotcha Auto-import feature may fail if the resolved file does not exist; smart fallback requires proper extension configuration. ↓

fix Ensure that the 'ext' option includes required extensions, e.g., raw({ ext: ['.ts', '.tsx'] })

gotcha When using the plugin with TSUP, ensure it is placed in the 'esbuildPlugins' array, not in 'plugins' which is for tsup plugins. ↓

fix Use `defineConfig({ esbuildPlugins: [raw()] })` instead of `plugins: [raw()]` in tsup config.

gotcha TypeScript declarations for raw imports (e.g., '*?raw') are required to avoid type errors; the plugin does not automatically generate them. ↓

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

Install

npm install esbuild-raw-plugin

yarn add esbuild-raw-plugin

pnpm add esbuild-raw-plugin

Imports

raw
wrong
```
const raw = require('esbuild-raw-plugin')
```
correct
```
import { raw } from 'esbuild-raw-plugin'
```
The package is ESM-only. CommonJS require will fail. Named export 'raw' is the plugin factory.

default

wrong

import { default as rawDefault } from 'esbuild-raw-plugin'

correct

import rawDefault from 'esbuild-raw-plugin'

A default export exists but is deprecated; prefer named import 'raw' for clarity.

RawPluginOptions

wrong

import { RawPluginOptions } from 'esbuild-raw-plugin' (when used as a type only, TypeScript may warn)

correct

import type { RawPluginOptions } from 'esbuild-raw-plugin'

TypeScript type import is recommended; if imported as value, it will be 'undefined' at runtime.

Quickstart

Shows how to add the raw plugin to ESBuild and import a file as raw text string.

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

build({
  entryPoints: ['src/index.js'],
  bundle: true,
  outfile: 'out.js',
  plugins: [raw()],
}).catch(() => process.exit(1));

// Then in your source:
import code from './example.js?raw';
console.log(code);