Skip to content

Commit 158d4b0

Browse files
mayank1513mayank1513
authored
Merge pull request #5 from react18-tools/fix-binary-loaders
Fix binary loaders
2 parents 028953e + 219a90a commit 158d4b0

File tree

9 files changed

+275
-154
lines changed

9 files changed

+275
-154
lines changed

‎.changeset/upgrade.md‎

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
---
2+
esbuild-raw-plugin: minor
3+
---
4+
5+
### ✨ Enhancements
6+
7+
- Replaced `textExtensions` with `customLoaders` for fine-grained extension-to-loader mapping.
8+
- Introduced `name` option for overriding the plugin name (useful for debugging or deduplication).
9+
- Added support for multiple query-based loaders: `?text`, `?base64`, `?dataurl`, `?file`, `?binary`.
10+
- Improved fallback logic for resolving files: now tries extensions or `index.[ext]` for folders.
11+
- Regex-based `onLoad` filtering boosts performance (leveraging Go-native ESBuild internals).
12+
13+
### 🛠 Internal Refactors
14+
15+
- Code refactored for better readability and maintainability.
16+
- Error messages are now clearer and more actionable.
17+
- Switched to consistent plugin naming (`"esbuild-raw-plugin"` instead of randomized suffix).

‎.gitignore‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@ node_modules
33
.turbo
44
*.log
55
.next
6-
dist
6+
dist*
77
dist-ssr
88
*.local
99
.env

‎README.md‎

Lines changed: 108 additions & 98 deletions
Original file line numberDiff line numberDiff line change
@@ -1,51 +1,57 @@
11
# Esbuild Raw Plugin <img src="https://raw.githubusercontent.com/mayank1513/mayank1513/main/popper.png" style="height: 40px"/>
22

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

5-
**An ESBuild/TSUP plugin to import files as raw text.**
6-
Ideal for scenarios like importing code files for documentation, interactive tools like `react-live`, or other text-based use cases.
11+
**Lightweight ESBuild/TSUP plugin to import files as raw content — zero config required.**
712

8-
> <img src="https://raw.githubusercontent.com/mayank1513/mayank1513/main/popper.png" style="height: 20px"/> Star [this repository](https://github.com/react18-tools/esbuild-raw-plugin) and share it with your friends.
13+
> Import `.ts`, `.js`, `.css`, `.scss`, `.md`, `.html`, `.docx`, and more — perfect for documentation, live editors (`react-live`), markdown tooling, or template-driven workflows.
14+
> Power users: Load `.docx` templates directly for [mdast2docx](https://github.com/md2docx/mdast2docx).
15+
16+
> <img src="https://raw.githubusercontent.com/mayank1513/mayank1513/main/popper.png" style="height: 20px"/> Star [this repository](https://github.com/react18-tools/esbuild-raw-plugin) and share it with your dev circle.
917
1018
---
1119

12-
## Features
20+
## 🚀 Features
1321

14-
- Import any file (e.g., `.js`, `.ts`, `.css`, etc.) as raw text.
15-
- Works seamlessly with **ESBuild** and **TSUP**.
16-
- Perfect for documentation generators, live code editors, and similar tools.
22+
- 🔧 Supports `?raw`, `?text`, `?base64`, `?dataurl`, `?binary`, and `?file` query suffixes
23+
- 🧠 Smart fallback to extensions like `.ts`, `.tsx`, `index.[ext]`, etc.
24+
- 🔍 Custom loader mapping (e.g., `module.scss` → `text`, `png` → `dataurl`)
25+
- ⚡ Ultra-fast using regex-based native `onLoad` filter (Go-native perf)
26+
- 🪶 Works seamlessly with both [Tsup](https://tsup.egoist.dev/) and [ESBuild](https://esbuild.github.io/)
1727

1828
---
1929

20-
## Installation
21-
22-
Using npm:
30+
## 📦 Installation
2331

2432
```bash
2533
npm install esbuild-raw-plugin --save-dev
2634
```
2735

28-
Using yarn:
36+
_or_
2937

3038
```bash
3139
yarn add esbuild-raw-plugin --dev
3240
```
3341

34-
Using pnpm:
42+
_or_
3543

3644
```bash
3745
pnpm add esbuild-raw-plugin --save-dev
3846
```
3947

4048
---
4149

42-
## Usage
50+
## 🛠 Usage
4351

44-
### ESBuild Configuration
52+
### ➤ With ESBuild
4553

46-
Add the plugin to your ESBuild configuration:
47-
48-
```js
54+
```ts
4955
import { build } from "esbuild";
5056
import { raw } from "esbuild-raw-plugin";
5157

@@ -57,11 +63,9 @@ build({
5763
});
5864
```
5965

60-
### TSUP Configuration
66+
### ➤ With TSUP
6167

62-
Add the plugin to your TSUP configuration:
63-
64-
```js
68+
```ts
6569
import { defineConfig } from "tsup";
6670
import { raw } from "esbuild-raw-plugin";
6771

@@ -74,135 +78,141 @@ export default defineConfig({
7478

7579
---
7680

77-
## IDE Setup for IntelliSense and Type Checking
81+
## 🧠 TypeScript Support
7882

79-
Add the following to your declaration file. If you do not have one, create a `declarations.d.ts` file and add the following:
83+
Add this to your `declarations.d.ts` file:
8084

81-
```typescript
85+
```ts
8286
declare module "*?raw" {
83-
const value: string;
84-
export default value;
87+
const content: string;
88+
export default content;
8589
}
8690
```
8791

88-
## Importing Files as Raw Text
92+
> For other suffixes (`?base64`, `?binary`, etc.), add similar declarations if needed.
93+
94+
---
8995

90-
With the plugin enabled, you can import files as raw text directly:
96+
## 📥 Importing Raw Files
9197

92-
```js
93-
import myCode from "./example.js?raw";
98+
```ts
99+
import content from "./example.js?raw";
94100

95-
console.log(myCode);
96-
// Outputs the content of 'example.js' as a string.
101+
console.log(content); // Entire file content as string or Buffer
97102
```
98103

99-
### Good News:
104+
### ✅ Simplified Imports
100105

101-
With the latest update, you no longer need to specify the file extension explicitly.
106+
You don’t need to specify full filenames or extensions:
102107

103-
```js
104-
import myCode from "./example?raw";
108+
```ts
109+
import code from "./utils?raw"; // Resolves to utils/index.ts, utils.js, etc.
105110
```
106111

107-
This works seamlessly! Additionally, if you're exporting from files like `index.tsx`, `index.jsx`, etc., you can simplify imports. For example, if your file path is `my-lib/index.ts`, you can import the raw content like this:
112+
Great for:
108113

109-
```js
110-
import myCode from "./my-lib?raw";
111-
```
114+
- Library or folder-level imports
115+
- Auto-resolving `.ts`, `.tsx`, `.css`, `.scss`, etc.
112116

113-
### Extension Options (Optional)
117+
---
118+
119+
## ⚙️ Plugin Options
114120

115121
```ts
116122
export interface RawPluginOptions {
117-
/**
118-
* Extensions to check in order if the file does not exist.
119-
* If it's a directory, the plugin will look for `dir/index.[ext]`.
120-
* @defaultValue ["tsx", "ts", "jsx", "js", "mjs", "mts", "module.css", "module.scss", "css", "scss"]
121-
*
122-
* You can provide your own extensions to optimize build performance or extend the list based on your use case.
123-
*/
124123
ext?: string[];
125-
126-
/**
127-
* Custom loader for file processing.
128-
* @defaultValue "text"
129-
*/
130124
loader?: "text" | "base64" | "dataurl" | "file" | "binary" | "default";
131-
132-
/**
133-
* Extensions to be treated as text files.
134-
*/
135-
textExtensions?: string[];
125+
customLoaders?: Record<string, "text" | "base64" | "dataurl" | "file" | "binary" | "default">;
126+
name?: string;
136127
}
137128
```
138129

139-
### Supported File Types
130+
<details>
131+
<summary><strong>🔧 Option Details</strong></summary>
140132

141-
You can use `?raw` with any file type, including:
133+
- `ext`: Extensions to resolve if the file or folder is missing. Defaults to common types like `ts`, `tsx`, `module.css`, etc.
134+
- `loader`: Default loader if no `?query` is specified. Usually `"text"`.
135+
- `customLoaders`: Per-extension loader mapping. Example:
142136

143-
- `.js`, `.ts`, `.jsx`, `.tsx`
144-
- `.css`, `.scss`
145-
- `.html`
146-
- `.md`
147-
- and more!
137+
```ts
138+
{
139+
"module.scss": "text",
140+
"png": "dataurl",
141+
"docx": "file"
142+
}
143+
```
148144

149-
---
145+
- `name`: Optional plugin name override for debugging or deduplication.
150146

151-
## Example Use Case
147+
</details>
152148

153-
### Live Code Preview with `react-live`
149+
---
154150

155-
```jsx
156-
import React from "react";
157-
import { LiveProvider, LiveEditor, LiveError, LivePreview } from "react-live";
158-
import exampleCode from "./example.js?raw";
151+
## 🧪 Supported Query Loaders
159152

160-
const App = () => (
161-
<LiveProvider code={exampleCode}>
162-
<LiveEditor />
163-
<LiveError />
164-
<LivePreview />
165-
</LiveProvider>
166-
);
153+
Import with query-based syntax:
167154

168-
export default App;
155+
```ts
156+
import doc from "./readme.md?text";
157+
import logo from "./logo.png?base64";
158+
import wasm from "./core.wasm?binary";
169159
```
170160

171-
---
172-
173-
## Why Use `esbuild-raw-plugin`?
174-
175-
- Simplifies importing files as raw text for documentation and live previews.
176-
- Seamlessly integrates with modern build tools like ESBuild and TSUP.
177-
- Lightweight and easy to configure.
161+
| Query Suffix | Description |
162+
| ------------ | -------------------------------------------------- |
163+
| `?raw` | Uses the default loader (options.loader ?? "text") |
164+
| `?text` | Loads file as UTF-8 text |
165+
| `?base64` | Returns base64 string |
166+
| `?dataurl` | Returns full data URL |
167+
| `?file` | Emits file to output dir |
168+
| `?binary` | Returns raw `Buffer` |
178169

179170
---
180171

181-
## Keywords
172+
## 🧬 Use Case: Live Code Preview
182173

183-
`esbuild`, `esbuild-plugin`, `tsup-plugin`, `raw-text-import`, `import-as-text`, `file-loader`, `react-live`, `documentation-tools`, `frontend-tooling`
174+
```tsx
175+
import { LiveProvider, LiveEditor, LiveError, LivePreview } from "react-live";
176+
import exampleCode from "./example.js?raw";
177+
178+
export default function LiveDemo() {
179+
return (
180+
<LiveProvider code={exampleCode}>
181+
<LiveEditor />
182+
<LiveError />
183+
<LivePreview />
184+
</LiveProvider>
185+
);
186+
}
187+
```
184188

185189
---
186190

187-
## Contributing
191+
## 🔍 Why Choose `esbuild-raw-plugin`?
188192

189-
Contributions are welcome!
190-
Feel free to open issues or pull requests to improve the plugin.
193+
- ✅ Works out of the box — no config needed
194+
- 📁 Handles smart file resolution
195+
- 💬 Excellent developer experience
196+
- 🧩 Supports both query-based and extension-based mappings
197+
- 🧪 Stable, fast, and production-tested
191198

192199
---
193200

194-
Let me know if you'd like further tweaks! 🚀
201+
## 🛠 Contributing
202+
203+
PRs and ideas welcome!
204+
Open an issue or submit a pull request to help improve the plugin.
195205

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

198208
---
199209

200-
## License
210+
## 🧾 License
201211

202-
This library is licensed under the MPL-2.0 open-source license.
212+
Licensed under the **MPL-2.0** open-source license.
203213

204-
> <img src="https://raw.githubusercontent.com/mayank1513/mayank1513/main/popper.png" style="height: 20px"/> Please enroll in [our courses](https://mayank-chaudhari.vercel.app/courses) or [sponsor](https://github.com/sponsors/mayank1513) our work.
214+
> <img src="https://raw.githubusercontent.com/mayank1513/mayank1513/main/popper.png" style="height: 20px"/> Please consider [sponsoring](https://github.com/sponsors/mayank1513) or [joining a course](https://mayank-chaudhari.vercel.app/courses) to support this work.
205215
206-
<hr />
216+
---
207217

208218
<p align="center" style="text-align:center">with 💖 by <a href="https://mayank-chaudhari.vercel.app" target="_blank">Mayank Kumar Chaudhari</a></p>

‎lib/__tests__/declarations.d.ts‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,2 +1,7 @@
1+
declare module "*?file";
2+
declare module "*?base64";
3+
declare module "*?binary";
4+
declare module "*?buffer";
5+
declare module "*?text";
16
declare module "*?raw";
27
declare module "*.md";

0 commit comments

Comments
 (0)