esbuild-raw-plugin

0.3.1 verified Fri May 01 auth: no javascript

An ESBuild and TSUP plugin for importing files as raw text, base64, dataurl, binary, or file content. v0.3.1 is current, released in February 2025. The plugin supports query suffixes like ?raw, ?text, ?base64, ?binary, ?dataurl, ?file, and smart extension resolution. It uses a fast regex-based onLoad filter, requires no configuration for common cases, and works as both an ESBuild plugin and a TSUP esbuildPlugin. Differentiators include zero-config setup, TypeScript declarations, and fallback resolution for folders and missing extensions.

Common errors

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

cause Package not installed or not in node_modules.

fix

Run 'npm install esbuild-raw-plugin --save-dev'

error TypeError: raw is not a function ↓

cause Using default import instead of named import.

fix

Use 'import { raw } from 'esbuild-raw-plugin''

error Module '"./code?raw"' has no default export ↓

cause Missing TypeScript module declaration for '?raw' suffix.

fix

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

error Error: No loader is configured for ".svg" files: file.svelte ↓

cause The plugin is not loaded or configured for that file type.

fix

Add 'customLoaders: { '.svg': 'text' }' to plugin options.

Warnings

breaking In v0.3.0, binary loaders were fixed. If you used v0.2.0 with binary imports, upgrade to v0.3.0+. ↓

fix Upgrade to esbuild-raw-plugin@^0.3.0

breaking In v0.1.0, automatic file extension resolution was introduced. Imports without extensions may resolve differently than in v0.0.0. ↓

fix Use explicit extensions or upgrade to v0.1.0+ and rely on auto-resolution.

deprecated The 'ext' option for custom extensions may be deprecated in future versions in favor of 'customLoaders'. ↓

fix Use 'customLoaders' instead of 'ext'.

gotcha When using TypeScript, you must add a module declaration for each query suffix (e.g., '*?raw') or type-checking will fail. ↓

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

gotcha The plugin uses regex-based onLoad filters; very large numbers of imports may cause performance issues. ↓

fix Use 'customLoaders' to whitelist specific file types rather than relying on query suffixes.

Install

npm install esraw

yarn add esraw

pnpm add esraw

Imports

raw

wrong

const raw = require('esbuild-raw-plugin');

correct

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

ESM-only; CJS require will fail. Named export, not default.

RawPluginOptions
```
import type { RawPluginOptions } from 'esbuild-raw-plugin'
```
TypeScript users must use type import for the options interface.
*?raw
wrong
```
import { content } from './example.js'
```
correct
```
import content from './example.js?raw'
```
Must append query suffix (?raw, ?text, etc.) to the import path. Default import, not named.

Quickstart

Set up ESBuild with the raw plugin and import a file as raw text.

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

await build({
  entryPoints: ['src/index.ts'],
  bundle: true,
  outfile: 'dist/bundle.js',
  plugins: [raw()],
});

// In your source file:
import code from './code?raw';
console.log(code); // raw content as string