esbuild-plugin-raw

0.3.0 verified Mon Apr 27 auth: no javascript

An esbuild plugin that allows importing file contents as raw strings. Version 0.3.0 supports esbuild ^0.14.36 through ^0.25.0. It is a simple, zero-config plugin that attaches to esbuild's resolve and load hooks. Unlike manual readFileSync or similar, it integrates seamlessly with esbuild's build pipeline and respects loaders. Typically used for embedding text files (e.g., shaders, markdown) in bundles. Ships TypeScript declarations.

Common errors

error Error: esbuild-plugin-raw: ESM-only package. Use dynamic import or a bundler that can handle ESM. ↓

cause The package is ESM-only. Using require() in CommonJS context throws.

fix

Use dynamic import: const RawPlugin = (await import('esbuild-plugin-raw')).default;

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

cause Missing installation or peer dependency esbuild not installed.

fix

Run 'npm install -D esbuild-plugin-raw esbuild'

error TypeError: RawPlugin is not a function ↓

cause Importing the default export incorrectly (e.g., named import).

fix

Use default import: import RawPlugin from 'esbuild-plugin-raw';

Warnings

gotcha Plugin only emits raw content for imports ending with '?raw'. Without the query, esbuild handles the file normally. ↓

fix Append '?raw' to all imports you want as raw strings, e.g., import data from './file.txt?raw'.

gotcha When using TypeScript, you may need to declare a module for '*.txt?raw' imports to avoid type errors. ↓

fix Add a declaration file: declare module '*?raw' { const content: string; export default content; }

gotcha The plugin does not work with esbuild v0.14.x and below (peer dependency range starts at 0.14.36). ↓

fix Upgrade esbuild to at least v0.14.36.

Install

npm install esbuild-plugin-raw

yarn add esbuild-plugin-raw

pnpm add esbuild-plugin-raw

Imports

RawPlugin
wrong
```
const RawPlugin = require('esbuild-plugin-raw')
```
correct
```
import RawPlugin from 'esbuild-plugin-raw'
```
Default export. The package is ESM-only; require() will fail unless using dynamic import or a bundler that can handle ESM.
esbuild-plugin-raw
wrong
```
import { RawPlugin } from 'esbuild-plugin-raw'
```
correct
```
import RawPlugin from 'esbuild-plugin-raw'
```
The plugin is exported as default, not as a named export. Named import will result in undefined.
TypeScript types
wrong
```
import { RawPlugin } from 'esbuild-plugin-raw'
```
correct
```
import type RawPlugin from 'esbuild-plugin-raw'
```
For TypeScript, use default import with type modifier for type-only imports if not using the value.

Quickstart

Shows basic usage: import the plugin, add it to esbuild plugins array, and then import files with ?raw suffix to get their contents as a string.

import esbuild from 'esbuild'
import RawPlugin from 'esbuild-plugin-raw'

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

// Then in a source file:
// import raw from './file.txt?raw'
// console.log(raw) // string content