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.docxtemplates 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?filequery 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
onLoadfilter (Go-native perf) - Works seamlessly with both Tsup and ESBuild
Installation
or
or
Usage
With ESBuild
import { raw } from "esbuild-raw-plugin";
build({
entryPoints: ["src/index.js"],
bundle: true,
outfile: "out.js",
plugins: [raw()],
});
With 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:
const content: string;
export default content;
}
For other suffixes (
?base64,?binary, etc.), add similar declarations if needed.
Importing Raw Files
console.log(content); // Entire file content as string or Buffer
Simplified Imports
You don't need to specify full filenames or extensions:
Great for:
- Library or folder-level imports
- Auto-resolving
.ts,.tsx,.css,.scss, etc.
Plugin Options
ext?: string[];
loader?: "text" | "base64" | "dataurl" | "file" | "binary" | "default";
customLoaders?: Record<string, "text" | "base64" | "dataurl" | "file" | "binary" | "default">;
name?: string;
}
Option Details
-
ext: Extensions to resolve if the file or folder is missing. Defaults to common types likets,tsx,module.css, etc. -
loader: Default loader if no?queryis specified. Usually"text". -
customLoaders: Per-extension loader mapping. Example:{
"module.scss": "text",
"png": "dataurl",
"docx": "file"
} -
name: Optional plugin name override for debugging or deduplication.
Supported Query Loaders
Import with query-based syntax:
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
import exampleCode from "./example.js?raw";
export default function LiveDemo() {
return (
<LiveProvider code={exampleCode}>
<LiveEditor />
<LiveError />
<LivePreview />
LiveProvider>
);
}
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.
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