An open API service indexing awesome lists of open source software.

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

Awesome Lists containing this project

README

          

# Esbuild Raw Plugin

[![test](https://github.com/react18-tools/esbuild-raw-plugin/actions/workflows/test.yml/badge.svg)](https://github.com/react18-tools/esbuild-raw-plugin/actions/workflows/test.yml)
[![Maintainability](https://api.codeclimate.com/v1/badges/aa896ec14c570f3bb274/maintainability)](https://codeclimate.com/github/react18-tools/esbuild-raw-plugin/maintainability)
[![codecov](https://codecov.io/gh/react18-tools/esbuild-raw-plugin/graph/badge.svg)](https://codecov.io/gh/react18-tools/esbuild-raw-plugin)
[![Version](https://img.shields.io/npm/v/esbuild-raw-plugin.svg?colorB=green)](https://www.npmjs.com/package/esbuild-raw-plugin)
[![Downloads](https://img.jsdelivr.com/img.shields.io/npm/d18m/esbuild-raw-plugin.svg)](https://www.npmjs.com/package/esbuild-raw-plugin)
![npm bundle size](https://img.shields.io/bundlephobia/minzip/esbuild-raw-plugin)
[![Gitpod ready-to-code](https://img.shields.io/badge/Gitpod-ready--to--code-blue?logo=gitpod)](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.

![Alt](https://repobeats.axiom.co/api/embed/1ae166ef108b33b36ceaa60be208a5dafce25c5c.svg "Repobeats analytics image")

---

## 🧾 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