https://github.com/react18-tools/esbuild-raw-plugin
ESBuild/TSUP plugin to import files as raw text β perfect for documentation and `react-live`.
https://github.com/react18-tools/esbuild-raw-plugin
code-snippets esbuild esbuild-plugin javascript live-editor nodejs raw-import react-live reactjs tsup tsup-plugin typescript
Last synced: 25 days ago
JSON representation
ESBuild/TSUP plugin to import files as raw text β perfect for documentation and `react-live`.
- Host: GitHub
- URL: https://github.com/react18-tools/esbuild-raw-plugin
- Owner: react18-tools
- License: mpl-2.0
- Created: 2024-12-16T11:07:39.000Z (10 months ago)
- Default Branch: main
- Last Pushed: 2025-09-17T08:24:40.000Z (28 days ago)
- Last Synced: 2025-09-17T10:25:37.528Z (28 days ago)
- Topics: code-snippets, esbuild, esbuild-plugin, javascript, live-editor, nodejs, raw-import, react-live, reactjs, tsup, tsup-plugin, typescript
- Language: JavaScript
- Homepage:
- Size: 2.45 MB
- Stars: 4
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Contributing: contributing.md
- Funding: .github/FUNDING.yml
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
- Security: SECURITY.md
Awesome Lists containing this project
README
# Esbuild Raw Plugin
[](https://github.com/react18-tools/esbuild-raw-plugin/actions/workflows/test.yml)
[](https://codeclimate.com/github/react18-tools/esbuild-raw-plugin/maintainability)
[](https://codecov.io/gh/react18-tools/esbuild-raw-plugin)
[](https://www.npmjs.com/package/esbuild-raw-plugin)
[](https://www.npmjs.com/package/esbuild-raw-plugin)

[](https://gitpod.io/from-referrer/)**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](https://github.com/md2docx/mdast2docx).>
Star [this repository](https://github.com/react18-tools/esbuild-raw-plugin) 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](https://tsup.egoist.dev/) and [ESBuild](https://esbuild.github.io/)---
## π¦ 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
### β€ With ESBuild
```ts
import { build } from "esbuild";
import { raw } from "esbuild-raw-plugin";build({
entryPoints: ["src/index.js"],
bundle: true,
outfile: "out.js",
plugins: [raw()],
});
```### β€ With TSUP
```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
```### β Simplified Imports
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;
}
```π§ Option Details
- `ext`: Extensions to resolve if the file or folder is missing. Defaults to common types like `ts`, `tsx`, `module.css`, etc.
- `loader`: Default loader if no `?query` is specified. Usually `"text"`.
- `customLoaders`: Per-extension loader mapping. Example:```ts
{
"module.scss": "text",
"png": "dataurl",
"docx": "file"
}
```- `name`: Optional plugin name override for debugging or deduplication.
---
## π§ͺ 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.
---
## π§Ύ License
Licensed under the **MPL-2.0** open-source license.
>
Please consider [sponsoring](https://github.com/sponsors/mayank1513) or [joining a course](https://mayank-chaudhari.vercel.app/courses) to support this work.
---
with π by Mayank Kumar Chaudhari