|
2 | 2 |
|
3 | 3 | [](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/) |
4 | 4 |
|
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. |
6 | 7 |
|
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. |
8 | 9 |
|
9 | | -✅ Fully TypeScript Supported |
| 10 | +--- |
10 | 11 |
|
11 | | -✅ Leverages the power of React 18 Server components |
| 12 | +## Features |
12 | 13 |
|
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. |
14 | 17 |
|
15 | | -✅ Documented with [Typedoc](https://react18-tools.github.io/esbuild-raw-plugin) ([Docs](https://react18-tools.github.io/esbuild-raw-plugin)) |
| 18 | +--- |
16 | 19 |
|
17 | | -✅ Examples for Next.js, Vite, and Remix |
| 20 | +## Installation |
18 | 21 |
|
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: |
20 | 23 |
|
21 | | -## Getting Started |
| 24 | +```bash |
| 25 | +npm install esbuild-raw-plugin --save-dev |
| 26 | +``` |
22 | 27 |
|
23 | | -### Installation |
| 28 | +Using yarn: |
24 | 29 |
|
25 | 30 | ```bash |
26 | | -pnpm add esbuild-raw-plugin |
| 31 | +yarn add esbuild-raw-plugin --dev |
27 | 32 | ``` |
28 | 33 |
|
29 | | -**_or_** |
| 34 | +Using pnpm: |
30 | 35 |
|
31 | 36 | ```bash |
32 | | -npm install esbuild-raw-plugin |
| 37 | +pnpm add esbuild-raw-plugin --save-dev |
33 | 38 | ``` |
34 | 39 |
|
35 | | -**_or_** |
| 40 | +--- |
36 | 41 |
|
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 | +}); |
39 | 58 | ``` |
40 | 59 |
|
41 | | -### Usage |
| 60 | +### TSUP Configuration |
42 | 61 |
|
43 | | -Using loaders is straightforward. |
| 62 | +Add the plugin to your TSUP configuration: |
44 | 63 |
|
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"; |
47 | 67 |
|
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 | +}); |
51 | 73 | ``` |
52 | 74 |
|
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 |
54 | 78 |
|
55 | | -**Using LoaderContainer** |
| 79 | +With the plugin enabled, you can import files as raw text directly: |
56 | 80 |
|
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"; |
58 | 83 |
|
59 | | -```tsx |
60 | | -// layout.tsx |
61 | | -<LoaderContainer /> |
62 | | - ... |
| 84 | +console.log(myCode); |
| 85 | +// Outputs the content of 'example.js' as a string. |
63 | 86 | ``` |
64 | 87 |
|
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; |
78 | 118 | ``` |
79 | 119 |
|
| 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 | + |
| 146 | + |
| 147 | +--- |
| 148 | + |
80 | 149 | ## License |
81 | 150 |
|
82 | 151 | This library is licensed under the MPL-2.0 open-source license. |
83 | 152 |
|
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. |
85 | 154 |
|
86 | 155 | <hr /> |
87 | 156 |
|
|
0 commit comments