Registry / http-networking / esbuild-raw-loader

esbuild-raw-loader

library0.3.1jsnpmunverified

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.

http-networking

npm install esbuild-raw-loader

github ↗package ↗

INSTALL

IMPORT

SIG · ESBUILD-RAW-LOADER

esbuild-raw-loader

http-networkingjavascriptv0.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'

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.

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

Debug

Known issues

breakingBinary 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

affects: <0.3.0

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

affects: >=0.2.0

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

affects: >=0.0.0

gotchaFor 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; }`

affects: >=0.0.0

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

affects: >=0.0.0

Errors

Common errors & fixes

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

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.

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

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.

TypeError: raw is not a function

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: Build failed with 1 error: error: Unexpected "?"

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.

Upgrade

Version history

0.3.1latest on npm

Audit

Dependencies

esbuildoptionalPeer dependency — plugin hooks into esbuild's build process via onLoad callback.

tsupoptionalOptional peer dependency — plugin can be used via tsup's esbuildPlugins config.

Agent activity

7 hits · last 30 days

node

OpenAI (training)

Resources

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

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