Registry / devops / esbuild-raw-plugin

esbuild-raw-plugin

library0.3.1jsnpmunverified

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.

devops web-framework serialization data

npm install esbuild-raw-plugin

github ↗package ↗

INSTALL

IMPORT

SIG · ESBUILD-RAW-PLUGIN

esbuild-raw-plugin

devopsjavascriptv0.3.1

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

raw

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

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

The package is ESM-only. CommonJS require will fail. Named export 'raw' is the plugin factory.

default

✓ import rawDefault from 'esbuild-raw-plugin'

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

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

RawPluginOptions

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

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

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

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);

Debug

Known issues

breakingBinary 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.

affects: <0.3.0

deprecatedDefault 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'`.

affects: >=0.2.0

gotchaAuto-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'] })

affects: >=0.0.0

gotchaWhen 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.

affects: >=0.0.0

gotchaTypeScript 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.

affects: >=0.0.0

Errors

Common errors & fixes

Cannot find module 'esbuild-raw-plugin'

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'`).

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

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: The plugin 'raw' must be an object with a 'name' property, or a function returning one.

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

fix

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

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

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'`.

Upgrade

Version history

0.3.1latest on npm

Audit

Dependencies

esbuildrequiredPeer dependency for using the plugin with ESBuild or TSUP (which depends on ESBuild internally).

Agent activity

2 hits · last 30 days

node

Resources

githubhttps://github.com/react18-tools/esbuild-raw-plugin ↗

packagehttps://www.npmjs.com/package/esbuild-raw-plugin ↗