Esbuild Raw Plugin

!npm bundle size

Lightweight ESBuild/TSUP plugin to import files as raw content — zero config required.

> 🔌Import .ts, .js, .css, .scss, .md, .html, .docx, and more — perfect for documentation, live editors (react-live), markdown tooling, or template-driven workflows.
> ⚡️Power users: Load .docx templates directly for mdast2docx.

> Star this repository and share it with your dev circle.

---

🚀 Features

> 🔥 Import any file as raw content with zero config in ESBuild or TSUP — text, base64, binary, docx templates & more!\
> ⚡️ Fast, smart, and extensible → esbuild-raw-plugin

- 🔧 Supports ?raw, ?text, ?base64, ?dataurl, ?binary, and ?file query suffixes
- 🧠 Smart fallback to extensions like .ts, .tsx, index.[ext], etc.
- 🔍 Custom loader mapping (e.g., module.scss → text, png → dataurl)
- ⚡ Ultra-fast using regex-based native onLoad filter (Go-native perf)
- 🪶 Works seamlessly with both Tsup and ESBuild

---

📦 Installation

``bash
npm install esbuild-raw-plugin --save-dev
`

_or_

`bash
yarn add esbuild-raw-plugin --dev
`

_or_

`bash
pnpm add esbuild-raw-plugin --save-dev
`

---

🛠 Usage

$3

`ts
import { build } from "esbuild";
import { raw } from "esbuild-raw-plugin";

build({
entryPoints: ["src/index.js"],
bundle: true,
outfile: "out.js",
plugins: [raw()],
});
`

$3

`ts
import { defineConfig } from "tsup";
import { raw } from "esbuild-raw-plugin";

export default defineConfig({
entry: ["src/index.ts"],
outDir: "dist",
esbuildPlugins: [raw()],
});
`

---

🧠 TypeScript Support

Add this to your declarations.d.ts file:

`ts
declare module "*?raw" {
const content: string;
export default content;
}
`

> For other suffixes (?base64, ?binary, etc.), add similar declarations if needed.

---

📥 Importing Raw Files

`ts
import content from "./example.js?raw";

console.log(content); // Entire file content as string or Buffer
`

$3

You don’t need to specify full filenames or extensions:

`ts
import code from "./utils?raw"; // Resolves to utils/index.ts, utils.js, etc.
`

Great for:

- Library or folder-level imports
- Auto-resolving .ts, .tsx, .css, .scss, etc.

---

⚙️ Plugin Options

`ts
export interface RawPluginOptions {
ext?: string[];
loader?: "text" | "base64" | "dataurl" | "file" | "binary" | "default";
customLoaders?: Record;
name?: string;
}
`

---

🧪 Supported Query Loaders

Import with query-based syntax:

`ts
import doc from "./readme.md?text";
import logo from "./logo.png?base64";
import wasm from "./core.wasm?binary";
`

| Query Suffix | Description |
| ------------ | -------------------------------------------------- |
| ?raw | Uses the default loader (options.loader ?? "text") |
| ?text | Loads file as UTF-8 text |
| ?base64 | Returns base64 string |
| ?dataurl | Returns full data URL |
| ?file | Emits file to output dir |
| ?binary | Returns raw Buffer |

---

🧬 Use Case: Live Code Preview

`tsx
import { LiveProvider, LiveEditor, LiveError, LivePreview } from "react-live";
import exampleCode from "./example.js?raw";

export default function LiveDemo() {
return (





);
}
`

---

🔍 Why Choose esbuild-raw-plugin`?

- ✅ Works out of the box — no config needed
- 📁 Handles smart file resolution
- 💬 Excellent developer experience
- 🧩 Supports both query-based and extension-based mappings
- 🧪 Stable, fast, and production-tested

---

🛠 Contributing

PRs and ideas welcome!
Open an issue or submit a pull request to help improve the plugin.

!Alt

---

🧾 License

Licensed under the MPL-2.0 open-source license.

> Please consider sponsoring or joining a course to support this work.

---

with 💖 by Mayank Kumar Chaudhari