Skip to content

Commit 244bfdf

Browse files
authored
docs: simplify setup and add loader option examples (#5)
1 parent dddfe3d commit 244bfdf

1 file changed

Lines changed: 184 additions & 67 deletions

File tree

‎README.md‎

Lines changed: 184 additions & 67 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,8 @@
11
# solid-loader
22

3-
A Rspack 2 loader for Solid 2 JSX and TSX. It uses Solid’s native compiler by default and supports hot module replacement (HMR) with Solid Refresh.
3+
A Rspack loader for Solid JSX and TSX, with built-in support for Solid Refresh.
4+
5+
Requires Solid 2.0.0 or later and Rspack 2.0.0 or later.
46

57
<p>
68
<a href="https://www.npmjs.com/package/solid-loader"><img src="https://img.shields.io/npm/v/solid-loader?style=flat-square&colorA=564341&colorB=EDED91" alt="npm version" /></a>
@@ -10,14 +12,19 @@ A Rspack 2 loader for Solid 2 JSX and TSX. It uses Solid’s native compiler by
1012

1113
## Usage
1214

13-
Install the Solid runtime and add the loader as a development dependency.
15+
Install the loader as a development dependency with your preferred package manager.
1416

1517
```sh
16-
pnpm add solid-js@2 @solidjs/web@2
18+
npm install -D solid-loader
19+
# or
1720
pnpm add -D solid-loader
21+
# or
22+
yarn add -D solid-loader
23+
# or
24+
bun add --dev solid-loader
1825
```
1926

20-
Add `solid-loader` to the JSX and TSX rule in `rspack.config.ts`. If your project already has an SWC rule for these files, add the loader to its `use` array as shown below.
27+
Add `solid-loader` after `builtin:swc-loader` in the `use` array for JSX and TSX files. Rspack runs loaders from right to left, so Solid compiles the JSX first and SWC then strips TypeScript types.
2128

2229
```ts
2330
// rspack.config.ts
@@ -33,7 +40,12 @@ export default defineConfig({
3340
{
3441
test: /\.[mc]?[jt]sx$/i,
3542
use: [
36-
{ loader: 'builtin:swc-loader', options: { detectSyntax: 'auto' } },
43+
{
44+
loader: 'builtin:swc-loader',
45+
options: {
46+
detectSyntax: 'auto',
47+
},
48+
},
3749
'solid-loader',
3850
],
3951
},
@@ -42,110 +54,215 @@ export default defineConfig({
4254
});
4355
```
4456

45-
Rspack runs loaders from right to left. In this rule, Solid compiles the JSX first. SWC then strips TypeScript types and transforms the remaining JavaScript for your target.
46-
47-
For TypeScript projects, set `jsx` to `"preserve"` and `jsxImportSource` to `"@solidjs/web"` in `tsconfig.json`.
57+
In TypeScript projects, set `jsx` to `"preserve"` and `jsxImportSource` to `"@solidjs/web"` in `tsconfig.json`.
4858

4959
## Solid Refresh
5060

51-
Solid Refresh runs automatically for browser development builds when Rspack enables HMR. Keep `'solid'` and `'development'` in your development resolve conditions so Solid uses its development runtime. See the [playground configuration](./playground/rspack.config.ts) for a complete example.
61+
Solid Refresh runs automatically during browser development when hot module replacement (HMR) is enabled. Include `'development'` alongside `'solid'` in your development resolve conditions to load Solid’s development runtime. The [playground configuration](./playground/rspack.config.ts) shows how to do this.
5262

5363
### Using a separate pre-loader
5464

55-
If another loader needs to run between Solid Refresh and JSX compilation, use `solid-loader/refresh` as a pre-loader and set `refresh: false` on the main loader. Integrations such as Rsbuild can then register components before a custom Babel transform runs.
56-
57-
```js
58-
{
59-
test: /\.[mc]?[jt]sx$/i,
60-
enforce: 'pre',
61-
exclude: /node_modules/,
62-
dependency: { not: 'url' },
63-
resourceQuery: { not: /[?&]raw(?:&|=|$)/ },
64-
with: { type: { not: 'text' } },
65-
loader: 'solid-loader/refresh',
66-
}
67-
```
65+
If a Babel transform needs to run between Solid Refresh and JSX compilation, set `refresh: false` on the main loader and register `solid-loader/refresh` with `enforce: 'pre'` in your browser development config. See the [pre-loader example](#granular).
6866

6967
## Server-side rendering
7068

71-
If the client will hydrate server-rendered HTML, enable `hydratable` in both builds. Set `solid.generate` to match the output each build needs.
69+
Set `solid.generate` to `'ssr'` in the server build. If the client hydrates the server-rendered HTML, enable `solid.hydratable` in both builds and keep the default `'dom'` output on the client.
7270

73-
| Build | Compiler options |
74-
| ---------------------------- | --------------------------------------- |
75-
| Server | `{ generate: 'ssr', hydratable: true }` |
76-
| Client hydrating server HTML | `{ generate: 'dom', hydratable: true }` |
71+
The [server configuration](#solid) also lets the Solid runtime load hydration modules by URL.
7772

78-
Add this rule so the Solid runtime can load hydration modules by URL.
73+
## Options
7974

80-
```js
81-
{
82-
descriptionData: { name: /^@solidjs\/web$/ },
83-
parser: { importDynamic: false },
84-
}
85-
```
75+
Set loader options in `module.rules` in your `rspack.config.ts`. The main loader exports the `SolidLoaderOptions` type, and `solid-loader/refresh` exports `SolidRefreshLoaderOptions`.
8676

87-
## Options
77+
### compiler
8878

89-
Pass options to the loader in the rule’s `use` array. This example selects the Babel backend.
79+
The loader uses Solid’s native compiler by default (`'native'`). Set `compiler` to `'babel'` to compile JSX with `@solidjs/babel-plugin`.
9080

9181
```ts
92-
const jsxRule = {
93-
test: /\.[mc]?[jt]sx$/i,
94-
use: [
95-
{ loader: 'builtin:swc-loader', options: { detectSyntax: 'auto' } },
96-
{ loader: 'solid-loader', options: { compiler: 'babel' } },
97-
],
82+
export default {
83+
module: {
84+
rules: [
85+
{
86+
test: /\.jsx$/i,
87+
loader: 'solid-loader',
88+
options: {
89+
compiler: 'babel',
90+
},
91+
},
92+
],
93+
},
9894
};
9995
```
10096

101-
For typed configurations, import `SolidLoaderOptions`, `SolidCompiler`, or `SolidPresetOptions` from `solid-loader`, and `SolidRefreshLoaderOptions` from `solid-loader/refresh`.
102-
103-
### compiler
104-
105-
- **Type:** `'native' | 'babel'`
106-
- **Default:** `'native'`
107-
108-
Selects the Solid JSX compiler. The default uses `@solidjs/compiler`. Set this to `'babel'` to compile with `@solidjs/babel-plugin`.
109-
11097
### refresh
11198

112-
- **Type:** `boolean`
113-
- **Default:** Enabled in development mode when HMR is active, the target supports the DOM, and `solid.generate` is not `'ssr'`.
99+
By default, Solid Refresh runs in development when HMR is enabled, the target supports the DOM, and the compiler is generating client output. Set `refresh` to `true` or `false` to override that behavior. For example, disable it on the main loader when using the [separate pre-loader](#using-a-separate-pre-loader).
114100

115-
Runs Solid Refresh before JSX compilation with either compiler. Set `false` to disable the built-in transform or `true` to enable it explicitly. Files in `node_modules` skip the Refresh transform and still go through JSX compilation.
101+
```ts
102+
export default {
103+
module: {
104+
rules: [
105+
{
106+
test: /\.jsx$/i,
107+
loader: 'solid-loader',
108+
options: {
109+
refresh: false,
110+
},
111+
},
112+
],
113+
},
114+
};
115+
```
116116

117117
### solid
118118

119-
- **Type:** `SolidPresetOptions`
119+
Pass options to the selected Solid compiler through `solid`. It generates DOM output by default and enables development transforms in Rspack’s development mode. For a server build that renders HTML for hydration, use the following settings.
120120

121-
Passes options to the selected compiler. By default, Solid generates DOM output and enables development transforms when Rspack runs in development mode. Set `solid.dev` to override that behavior, or use `solid.generate` and `solid.hydratable` to configure [server-side rendering](#server-side-rendering).
121+
```ts
122+
export default {
123+
target: 'node',
124+
module: {
125+
rules: [
126+
{
127+
test: /\.jsx$/i,
128+
loader: 'solid-loader',
129+
options: {
130+
solid: {
131+
generate: 'ssr',
132+
hydratable: true,
133+
},
134+
},
135+
},
136+
{
137+
descriptionData: {
138+
name: /^@solidjs\/web$/,
139+
},
140+
parser: {
141+
importDynamic: false,
142+
},
143+
},
144+
],
145+
},
146+
};
147+
```
122148

123149
### decoratorVersion
124150

125-
- **Type:** `'legacy' | '2022-03' | '2023-11'`
151+
The Babel backend parses standard decorators by default. Both `'2022-03'` and `'2023-11'` use that parser. Choose `'legacy'` if your code uses legacy decorator syntax.
126152

127-
Controls how the Babel backend parses decorators. Set this to `'legacy'` if your source uses legacy decorator syntax. Both dated values select Babel’s standard decorators parser, which is also the default when you omit this option.
153+
```ts
154+
export default {
155+
module: {
156+
rules: [
157+
{
158+
test: /\.jsx$/i,
159+
use: [
160+
{
161+
loader: 'builtin:swc-loader',
162+
options: {
163+
jsc: {
164+
parser: {
165+
syntax: 'ecmascript',
166+
decorators: true,
167+
},
168+
transform: {
169+
legacyDecorator: true,
170+
},
171+
},
172+
},
173+
},
174+
{
175+
loader: 'solid-loader',
176+
options: {
177+
compiler: 'babel',
178+
decoratorVersion: 'legacy',
179+
},
180+
},
181+
],
182+
},
183+
],
184+
},
185+
};
186+
```
128187

129188
### scriptRegex
130189

131-
- **Type:** `RegExp`
190+
By default, the loader processes every file matched by the Rspack rule. If the rule also handles plain TypeScript, use `scriptRegex` to compile only TSX files and pass the rest through to the next loader.
132191

133-
Filters the files the loader compiles. For example, if a shared rule handles both `.ts` and `.tsx`, use `scriptRegex: /\.tsx$/i` to pass plain TypeScript through to the next loader. By default, the loader processes every file that matches the Rspack rule.
192+
```ts
193+
export default {
194+
module: {
195+
rules: [
196+
{
197+
test: /\.tsx?$/i,
198+
use: [
199+
{
200+
loader: 'builtin:swc-loader',
201+
options: {
202+
detectSyntax: 'auto',
203+
},
204+
},
205+
{
206+
loader: 'solid-loader',
207+
options: {
208+
scriptRegex: /\.tsx$/i,
209+
},
210+
},
211+
],
212+
},
213+
],
214+
},
215+
};
216+
```
134217

135218
### transformFilename
136219

137-
- **Type:** `string`
138-
- **Default:** The resource path supplied by Rspack.
220+
The loader normally uses the resource path to match `scriptRegex` and choose a parser. Give an inline module a filename such as `'data-uri.jsx'` to parse it as JSX. Source maps still point to the original resource.
139221

140-
Sets the filename used for the `scriptRegex` check and for choosing the JSX or TSX parser. For example, use `transformFilename: 'data-uri.jsx'` for a rule that handles inline JSX modules. Source maps still point to the original resource.
222+
```ts
223+
export default {
224+
module: {
225+
rules: [
226+
{
227+
scheme: 'data',
228+
mimetype: 'text/javascript',
229+
loader: 'solid-loader',
230+
options: {
231+
transformFilename: 'data-uri.jsx',
232+
},
233+
},
234+
],
235+
},
236+
};
237+
```
141238

142239
### granular
143240

144-
- **Loader:** `solid-loader/refresh`
145-
- **Type:** `boolean`
146-
- **Default:** `true`
241+
The `solid-loader/refresh` pre-loader tracks changes per component by default so edits can preserve state in unaffected components. Set `granular` to `false` on the pre-loader to turn off this tracking while keeping HMR enabled.
147242

148-
Adds per-component metadata so Solid Refresh can limit which components remount after an edit. Set `granular: false` on the refresh loader to disable that tracking while keeping HMR enabled.
243+
```ts
244+
export default {
245+
module: {
246+
rules: [
247+
{
248+
test: /\.jsx$/i,
249+
enforce: 'pre',
250+
loader: 'solid-loader/refresh',
251+
options: {
252+
granular: false,
253+
},
254+
},
255+
{
256+
test: /\.jsx$/i,
257+
loader: 'solid-loader',
258+
options: {
259+
refresh: false,
260+
},
261+
},
262+
],
263+
},
264+
};
265+
```
149266

150267
## License
151268

0 commit comments

Comments
 (0)