Skip to content

Commit 7f50bf4

Browse files
committed
update readme
1 parent de8e168 commit 7f50bf4

File tree

1 file changed

+113
-44
lines changed

1 file changed

+113
-44
lines changed

README.md

Lines changed: 113 additions & 44 deletions
Original file line numberDiff line numberDiff line change
@@ -2,86 +2,155 @@
22

33
[![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/)
44

5-
Esbuild Raw Plugin is a comprehensive library designed to unlock the full potential of React 18 server components. It provides customizable loading animation components and a fullscreen loader container, seamlessly integrating with React and Next.js.
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.
67

7-
✅ Fully Treeshakable (import from `esbuild-raw-plugin/client/loader-container`)
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.
89
9-
✅ Fully TypeScript Supported
10+
---
1011

11-
✅ Leverages the power of React 18 Server components
12+
## Features
1213

13-
✅ Compatible with all React 18 build systems/tools/frameworks
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.
1417

15-
✅ Documented with [Typedoc](https://react18-tools.github.io/esbuild-raw-plugin) ([Docs](https://react18-tools.github.io/esbuild-raw-plugin))
18+
---
1619

17-
✅ Examples for Next.js, Vite, and Remix
20+
## Installation
1821

19-
> <img src="https://raw.githubusercontent.com/mayank1513/mayank1513/main/popper.png" style="height: 20px"/> Please consider starring [this repository](https://github.com/react18-tools/esbuild-raw-plugin) and sharing it with your friends.
22+
Using npm:
2023

21-
## Getting Started
24+
```bash
25+
npm install esbuild-raw-plugin --save-dev
26+
```
2227

23-
### Installation
28+
Using yarn:
2429

2530
```bash
26-
pnpm add esbuild-raw-plugin
31+
yarn add esbuild-raw-plugin --dev
2732
```
2833

29-
**_or_**
34+
Using pnpm:
3035

3136
```bash
32-
npm install esbuild-raw-plugin
37+
pnpm add esbuild-raw-plugin --save-dev
3338
```
3439

35-
**_or_**
40+
---
3641

37-
```bash
38-
yarn add esbuild-raw-plugin
42+
## Usage
43+
44+
### ESBuild Configuration
45+
46+
Add the plugin to your ESBuild configuration:
47+
48+
```js
49+
import { build } from "esbuild";
50+
import { raw } from "esbuild-raw-plugin";
51+
52+
build({
53+
entryPoints: ["src/index.js"],
54+
bundle: true,
55+
outfile: "out.js",
56+
plugins: [raw()],
57+
});
3958
```
4059

41-
### Usage
60+
### TSUP Configuration
4261

43-
Using loaders is straightforward.
62+
Add the plugin to your TSUP configuration:
4463

45-
```tsx
46-
import { Bars1 } from "esbuild-raw-plugin/dist/server/bars/bars1";
64+
```js
65+
import { defineConfig } from "tsup";
66+
import { raw } from "esbuild-raw-plugin";
4767

48-
export default function MyComponent() {
49-
return someCondition ? <Bars1 /> : <>Something else...</>;
50-
}
68+
export default defineConfig({
69+
entry: ["src/index.ts"],
70+
outDir: "dist",
71+
plugins: [raw()],
72+
});
5173
```
5274

53-
For detailed API and options, refer to [the API documentation](https://react18-tools.github.io/esbuild-raw-plugin).
75+
---
76+
77+
## Importing Files as Raw Text
5478

55-
**Using LoaderContainer**
79+
With the plugin enabled, you can import files as raw text directly:
5680

57-
`LoaderContainer` is a fullscreen component. You can add this component directly in your layout and then use `useLoader` hook to toggle its visibility.
81+
```js
82+
import myCode from "./example.js?raw";
5883

59-
```tsx
60-
// layout.tsx
61-
<LoaderContainer />
62-
...
84+
console.log(myCode);
85+
// Outputs the content of 'example.js' as a string.
6386
```
6487

65-
```tsx
66-
// some other page or component
67-
import { useLoader } from "esbuild-raw-plugin/dist/hooks";
68-
69-
export default MyComponent() {
70-
const { setLoading } = useLoader();
71-
useCallback(()=>{
72-
setLoading(true);
73-
...do some work
74-
setLoading(false);
75-
}, [])
76-
...
77-
}
88+
### Supported File Types
89+
90+
You can use `?raw` with any file type, including:
91+
92+
- `.js`, `.ts`, `.jsx`, `.tsx`
93+
- `.css`, `.scss`
94+
- `.html`
95+
- `.md`
96+
- and more!
97+
98+
---
99+
100+
## Example Use Case
101+
102+
### Live Code Preview with `react-live`
103+
104+
```jsx
105+
import React from "react";
106+
import { LiveProvider, LiveEditor, LiveError, LivePreview } from "react-live";
107+
import exampleCode from "./example.js?raw";
108+
109+
const App = () => (
110+
<LiveProvider code={exampleCode}>
111+
<LiveEditor />
112+
<LiveError />
113+
<LivePreview />
114+
</LiveProvider>
115+
);
116+
117+
export default App;
78118
```
79119

120+
---
121+
122+
## Why Use `esbuild-raw-plugin`?
123+
124+
- Simplifies importing files as raw text for documentation and live previews.
125+
- Seamlessly integrates with modern build tools like ESBuild and TSUP.
126+
- Lightweight and easy to configure.
127+
128+
---
129+
130+
## Keywords
131+
132+
`esbuild`, `esbuild-plugin`, `tsup-plugin`, `raw-text-import`, `import-as-text`, `file-loader`, `react-live`, `documentation-tools`, `frontend-tooling`
133+
134+
---
135+
136+
## Contributing
137+
138+
Contributions are welcome!
139+
Feel free to open issues or pull requests to improve the plugin.
140+
141+
---
142+
143+
Let me know if you'd like further tweaks! 🚀
144+
145+
![Alt](https://repobeats.axiom.co/api/embed/1ae166ef108b33b36ceaa60be208a5dafce25c5c.svg "Repobeats analytics image")
146+
147+
---
148+
80149
## License
81150

82151
This library is licensed under the MPL-2.0 open-source license.
83152

84-
> <img src="https://raw.githubusercontent.com/mayank1513/mayank1513/main/popper.png" style="height: 20px"/> Please consider enrolling in [our courses](https://mayank-chaudhari.vercel.app/courses) or [sponsoring](https://github.com/sponsors/mayank1513) our work.
153+
> <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.
85154
86155
<hr />
87156

0 commit comments

Comments
 (0)