esbuild-raw-plugin

0.3.1 verified Fri May 01 auth: no javascript

An ESBuild and TSUP plugin (v0.3.1) that imports files as raw text, base64, data URL, binary, or file content via query suffixes like ?raw, ?text, ?base64, ?dataurl, ?binary, and ?file. Supports smart extension resolution and custom loader mappings. Currently stable with monthly releases. Differentiates from similar plugins by supporting multiple output formats, zero-config setup, and compatibility with both esbuild and tsup.

Common errors

error Error: The plugin "esbuild-raw-plugin" doesn't have a setup function ↓

cause Using an older version (pre-0.1.0) that exported a factory instead of a direct plugin function.

fix

Upgrade to latest version: npm install esbuild-raw-plugin@latest

error Module not found: Error: Can't resolve './example.js?raw' ↓

cause Missing esbuild plugin configuration; plugin not added to plugins array.

fix

Ensure raw() is included in the esbuild plugins array.

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

cause Missing type declaration for ?raw imports.

fix

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

Warnings

breaking Version 0.3.0 changed binary loaders; ensure ?binary suffix works as expected. ↓

fix Update to v0.3.1 for backward compatibility fixes.

gotcha Query suffix like ?raw is resolved before extension; ensure your bundler configuration does not interfere with esbuild's resolver. ↓

fix Test that imports with suffixes work; if not, check for custom resolvers or other plugins.

gotcha For TypeScript projects, you must add module declarations for suffixes like ?raw to avoid type errors. ↓

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

deprecated Version 0.1.0 introduced autocomplete extension resolution; direct filename may no longer be necessary. ↓

fix Use `import code from './utils?raw'` instead of specifying full path.

Install

npm install esbuild-raw

yarn add esbuild-raw

pnpm add esbuild-raw

Imports

raw

wrong

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

correct

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

ESM-only since v0.1.0; CommonJS require will not work.

raw (default import)
```
import raw from 'esbuild-raw-plugin'
```
Default export is also available but typed as the same function; prefer named import for clarity.

RawPluginOptions

wrong

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

correct

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

This is a TypeScript type, not a runtime value; use type import to avoid bundling issues.

Quickstart

Shows basic setup with ESBuild and import of a file as raw text using the ?raw suffix.

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

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

// In src/index.ts:
import code from './example.js?raw';
console.log(code); // string content of example.js