Skip to content

Commit 606c5c1

Browse files
mayank1513mayank1513
committed
Apply changesets and update CHANGELOG
1 parent f174364 commit 606c5c1

File tree

1 file changed

+123
-43
lines changed

1 file changed

+123
-43
lines changed

‎lib/README.md‎

Lines changed: 123 additions & 43 deletions
Original file line numberDiff line numberDiff line change
@@ -2,86 +2,166 @@
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";
67+
68+
export default defineConfig({
69+
entry: ["src/index.ts"],
70+
outDir: "dist",
71+
plugins: [raw()],
72+
});
73+
```
4774

48-
export default function MyComponent() {
49-
return someCondition ? <Bars1 /> : <>Something else...</>;
75+
---
76+
77+
## IDE Setup for IntelliSense and Type Checking
78+
79+
Add following to your declaration file. If you do not have one, create `declarations.d.ts` file and add following.
80+
81+
```typescript
82+
declare module "*?raw" {
83+
const value: string;
84+
export default value;
5085
}
5186
```
5287

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

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

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

59-
```tsx
60-
// layout.tsx
61-
<LoaderContainer />
62-
...
95+
console.log(myCode);
96+
// Outputs the content of 'example.js' as a string.
6397
```
6498

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-
}
99+
### Supported File Types
100+
101+
You can use `?raw` with any file type, including:
102+
103+
- `.js`, `.ts`, `.jsx`, `.tsx`
104+
- `.css`, `.scss`
105+
- `.html`
106+
- `.md`
107+
- and more!
108+
109+
---
110+
111+
## Example Use Case
112+
113+
### Live Code Preview with `react-live`
114+
115+
```jsx
116+
import React from "react";
117+
import { LiveProvider, LiveEditor, LiveError, LivePreview } from "react-live";
118+
import exampleCode from "./example.js?raw";
119+
120+
const App = () => (
121+
<LiveProvider code={exampleCode}>
122+
<LiveEditor />
123+
<LiveError />
124+
<LivePreview />
125+
</LiveProvider>
126+
);
127+
128+
export default App;
78129
```
79130

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

82162
This library is licensed under the MPL-2.0 open-source license.
83163

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.
164+
> <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.
85165
86166
<hr />
87167

0 commit comments

Comments
 (0)