esraw

library0.3.1jsnpmunverified

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.

devops

npm install esraw

github ↗package ↗

INSTALL

IMPORT

SIG · ESRAW

esraw

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

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

✓ import content from './example.js?raw'

✗ import { content } from './example.js'

Must append query suffix (?raw, ?text, etc.) to the import path. Default import, not named.

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

Debug

Known issues

breakingIn 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

affects: >=0.2.0 <0.3.0

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

affects: >=0.0.0 <0.1.0

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

fix

Use 'customLoaders' instead of 'ext'.

affects: >=0.1.0

gotchaWhen 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

affects: >=0.0.0

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

affects: >=0.0.0

Errors

Common errors & fixes

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

Package not installed or not in node_modules.

fix

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

TypeError: raw is not a function

Using default import instead of named import.

fix

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

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

Missing TypeScript module declaration for '?raw' suffix.

fix

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

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

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

fix

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

Upgrade

Version history

0.3.1latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

7 hits · last 30 days

node

Resources

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

packagehttps://www.npmjs.com/package/esraw ↗