From 4f5e3fb38e712db1cfe1985e08a9237229da0731 Mon Sep 17 00:00:00 2001 From: neverland Date: Thu, 19 Nov 2026 10:19:10 +0800 Subject: [PATCH 1/3] docs: simplify setup and add loader option examples --- README.md | 106 ++++++++++++++++++++++++++---------------------------- 1 file changed, 51 insertions(+), 55 deletions(-) diff --git a/README.md b/README.md index 10757ae..1fb1a94 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,8 @@ # solid-loader -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. +A Rspack loader for Solid JSX and TSX, with built-in support for Solid Refresh. + +Requires Solid 2.0.0 or later and Rspack 2.0.0 or later.

npm version @@ -10,14 +12,19 @@ A Rspack 2 loader for Solid 2 JSX and TSX. It uses Solid’s native compiler by ## Usage -Install the Solid runtime and add the loader as a development dependency. +Install the loader as a development dependency with your preferred package manager. ```sh -pnpm add solid-js@2 @solidjs/web@2 +npm install -D solid-loader +# or pnpm add -D solid-loader +# or +yarn add -D solid-loader +# or +bun add --dev solid-loader ``` -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. +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. ```ts // rspack.config.ts @@ -42,110 +49,99 @@ export default defineConfig({ }); ``` -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. - -For TypeScript projects, set `jsx` to `"preserve"` and `jsxImportSource` to `"@solidjs/web"` in `tsconfig.json`. +In TypeScript projects, set `jsx` to `"preserve"` and `jsxImportSource` to `"@solidjs/web"` in `tsconfig.json`. ## Solid Refresh -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. +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. ### Using a separate pre-loader -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. +If a Babel transform needs to run between Solid Refresh and JSX compilation, set `refresh: false` on the main loader and add this rule to your browser development config. Rspack will run it before the other loaders. -```js -{ +```ts +const refreshRule = { test: /\.[mc]?[jt]sx$/i, enforce: 'pre', - exclude: /node_modules/, dependency: { not: 'url' }, resourceQuery: { not: /[?&]raw(?:&|=|$)/ }, with: { type: { not: 'text' } }, loader: 'solid-loader/refresh', -} +} as const; ``` ## Server-side rendering -If the client will hydrate server-rendered HTML, enable `hydratable` in both builds. Set `solid.generate` to match the output each build needs. - -| Build | Compiler options | -| ---------------------------- | --------------------------------------- | -| Server | `{ generate: 'ssr', hydratable: true }` | -| Client hydrating server HTML | `{ generate: 'dom', hydratable: true }` | +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. -Add this rule so the Solid runtime can load hydration modules by URL. +Add this rule to let the Solid runtime load hydration modules by URL. -```js -{ +```ts +const runtimeRule = { descriptionData: { name: /^@solidjs\/web$/ }, parser: { importDynamic: false }, -} +}; ``` ## Options -Pass options to the loader in the rule’s `use` array. This example selects the Babel backend. - -```ts -const jsxRule = { - test: /\.[mc]?[jt]sx$/i, - use: [ - { loader: 'builtin:swc-loader', options: { detectSyntax: 'auto' } }, - { loader: 'solid-loader', options: { compiler: 'babel' } }, - ], -}; -``` - -For typed configurations, import `SolidLoaderOptions`, `SolidCompiler`, or `SolidPresetOptions` from `solid-loader`, and `SolidRefreshLoaderOptions` from `solid-loader/refresh`. +To configure the loader, replace `'solid-loader'` in the `use` array with an object such as `{ loader: 'solid-loader', options: { compiler: 'babel' } }`. The examples below show what to put in `options`. In TypeScript, use `SolidLoaderOptions` from `solid-loader` for the main loader or `SolidRefreshLoaderOptions` from `solid-loader/refresh` for the pre-loader. ### compiler -- **Type:** `'native' | 'babel'` -- **Default:** `'native'` +The loader uses Solid’s native compiler by default (`'native'`). Set `compiler` to `'babel'` to compile JSX with `@solidjs/babel-plugin`. -Selects the Solid JSX compiler. The default uses `@solidjs/compiler`. Set this to `'babel'` to compile with `@solidjs/babel-plugin`. +```ts +const options = { compiler: 'babel' }; +``` ### refresh -- **Type:** `boolean` -- **Default:** Enabled in development mode when HMR is active, the target supports the DOM, and `solid.generate` is not `'ssr'`. +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). -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. +```ts +const options = { refresh: false }; +``` ### solid -- **Type:** `SolidPresetOptions` +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. -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). +```ts +const options = { solid: { generate: 'ssr', hydratable: true } }; +``` ### decoratorVersion -- **Type:** `'legacy' | '2022-03' | '2023-11'` +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. -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. +```ts +const options = { compiler: 'babel', decoratorVersion: 'legacy' }; +``` ### scriptRegex -- **Type:** `RegExp` +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. -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. +```ts +const options = { scriptRegex: /\.tsx$/i }; +``` ### transformFilename -- **Type:** `string` -- **Default:** The resource path supplied by Rspack. +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. -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. +```ts +const options = { transformFilename: 'data-uri.jsx' }; +``` ### granular -- **Loader:** `solid-loader/refresh` -- **Type:** `boolean` -- **Default:** `true` +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. -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. +```ts +const options = { granular: false }; +``` ## License From 23441e37a8383fbdbf13b43c992f69f6c55ae745 Mon Sep 17 00:00:00 2001 From: neverland Date: Thu, 19 Nov 2026 10:23:27 +0800 Subject: [PATCH 2/3] docs: show loader options in complete Rspack configs --- README.md | 135 +++++++++++++++++++++++++++++++++++++++++++----------- 1 file changed, 107 insertions(+), 28 deletions(-) diff --git a/README.md b/README.md index 1fb1a94..f6814ff 100644 --- a/README.md +++ b/README.md @@ -57,42 +57,34 @@ Solid Refresh runs automatically during browser development when hot module repl ### Using a separate pre-loader -If a Babel transform needs to run between Solid Refresh and JSX compilation, set `refresh: false` on the main loader and add this rule to your browser development config. Rspack will run it before the other loaders. - -```ts -const refreshRule = { - test: /\.[mc]?[jt]sx$/i, - enforce: 'pre', - dependency: { not: 'url' }, - resourceQuery: { not: /[?&]raw(?:&|=|$)/ }, - with: { type: { not: 'text' } }, - loader: 'solid-loader/refresh', -} as const; -``` +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). ## Server-side rendering 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. -Add this rule to let the Solid runtime load hydration modules by URL. - -```ts -const runtimeRule = { - descriptionData: { name: /^@solidjs\/web$/ }, - parser: { importDynamic: false }, -}; -``` +The [server configuration](#solid) also lets the Solid runtime load hydration modules by URL. ## Options -To configure the loader, replace `'solid-loader'` in the `use` array with an object such as `{ loader: 'solid-loader', options: { compiler: 'babel' } }`. The examples below show what to put in `options`. In TypeScript, use `SolidLoaderOptions` from `solid-loader` for the main loader or `SolidRefreshLoaderOptions` from `solid-loader/refresh` for the pre-loader. +Set loader options in `module.rules` in your `rspack.config.ts`. The main loader exports the `SolidLoaderOptions` type, and `solid-loader/refresh` exports `SolidRefreshLoaderOptions`. ### compiler The loader uses Solid’s native compiler by default (`'native'`). Set `compiler` to `'babel'` to compile JSX with `@solidjs/babel-plugin`. ```ts -const options = { compiler: 'babel' }; +export default { + module: { + rules: [ + { + test: /\.jsx$/i, + loader: 'solid-loader', + options: { compiler: 'babel' }, + }, + ], + }, +}; ``` ### refresh @@ -100,7 +92,17 @@ const options = { compiler: 'babel' }; 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). ```ts -const options = { refresh: false }; +export default { + module: { + rules: [ + { + test: /\.jsx$/i, + loader: 'solid-loader', + options: { refresh: false }, + }, + ], + }, +}; ``` ### solid @@ -108,7 +110,22 @@ const options = { refresh: false }; 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. ```ts -const options = { solid: { generate: 'ssr', hydratable: true } }; +export default { + target: 'node', + module: { + rules: [ + { + test: /\.jsx$/i, + loader: 'solid-loader', + options: { solid: { generate: 'ssr', hydratable: true } }, + }, + { + descriptionData: { name: /^@solidjs\/web$/ }, + parser: { importDynamic: false }, + }, + ], + }, +}; ``` ### decoratorVersion @@ -116,7 +133,30 @@ const options = { solid: { generate: 'ssr', hydratable: true } }; 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. ```ts -const options = { compiler: 'babel', decoratorVersion: 'legacy' }; +export default { + module: { + rules: [ + { + test: /\.jsx$/i, + use: [ + { + loader: 'builtin:swc-loader', + options: { + jsc: { + parser: { syntax: 'ecmascript', decorators: true }, + transform: { legacyDecorator: true }, + }, + }, + }, + { + loader: 'solid-loader', + options: { compiler: 'babel', decoratorVersion: 'legacy' }, + }, + ], + }, + ], + }, +}; ``` ### scriptRegex @@ -124,7 +164,19 @@ const options = { compiler: 'babel', decoratorVersion: 'legacy' }; 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. ```ts -const options = { scriptRegex: /\.tsx$/i }; +export default { + module: { + rules: [ + { + test: /\.tsx?$/i, + use: [ + { loader: 'builtin:swc-loader', options: { detectSyntax: 'auto' } }, + { loader: 'solid-loader', options: { scriptRegex: /\.tsx$/i } }, + ], + }, + ], + }, +}; ``` ### transformFilename @@ -132,7 +184,18 @@ const options = { scriptRegex: /\.tsx$/i }; 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. ```ts -const options = { transformFilename: 'data-uri.jsx' }; +export default { + module: { + rules: [ + { + scheme: 'data', + mimetype: 'text/javascript', + loader: 'solid-loader', + options: { transformFilename: 'data-uri.jsx' }, + }, + ], + }, +}; ``` ### granular @@ -140,7 +203,23 @@ const options = { transformFilename: 'data-uri.jsx' }; 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. ```ts -const options = { granular: false }; +export default { + module: { + rules: [ + { + test: /\.jsx$/i, + enforce: 'pre', + loader: 'solid-loader/refresh', + options: { granular: false }, + }, + { + test: /\.jsx$/i, + loader: 'solid-loader', + options: { refresh: false }, + }, + ], + }, +}; ``` ## License From 910a77f8dfed1282f04bed6a2b2335de686e0ff4 Mon Sep 17 00:00:00 2001 From: neverland Date: Thu, 19 Nov 2026 10:31:44 +0800 Subject: [PATCH 3/3] docs: expand nested objects in configuration examples --- README.md | 70 ++++++++++++++++++++++++++++++++++++++++++++----------- 1 file changed, 56 insertions(+), 14 deletions(-) diff --git a/README.md b/README.md index f6814ff..8ab7bbd 100644 --- a/README.md +++ b/README.md @@ -40,7 +40,12 @@ export default defineConfig({ { test: /\.[mc]?[jt]sx$/i, use: [ - { loader: 'builtin:swc-loader', options: { detectSyntax: 'auto' } }, + { + loader: 'builtin:swc-loader', + options: { + detectSyntax: 'auto', + }, + }, 'solid-loader', ], }, @@ -80,7 +85,9 @@ export default { { test: /\.jsx$/i, loader: 'solid-loader', - options: { compiler: 'babel' }, + options: { + compiler: 'babel', + }, }, ], }, @@ -98,7 +105,9 @@ export default { { test: /\.jsx$/i, loader: 'solid-loader', - options: { refresh: false }, + options: { + refresh: false, + }, }, ], }, @@ -117,11 +126,20 @@ export default { { test: /\.jsx$/i, loader: 'solid-loader', - options: { solid: { generate: 'ssr', hydratable: true } }, + options: { + solid: { + generate: 'ssr', + hydratable: true, + }, + }, }, { - descriptionData: { name: /^@solidjs\/web$/ }, - parser: { importDynamic: false }, + descriptionData: { + name: /^@solidjs\/web$/, + }, + parser: { + importDynamic: false, + }, }, ], }, @@ -143,14 +161,22 @@ export default { loader: 'builtin:swc-loader', options: { jsc: { - parser: { syntax: 'ecmascript', decorators: true }, - transform: { legacyDecorator: true }, + parser: { + syntax: 'ecmascript', + decorators: true, + }, + transform: { + legacyDecorator: true, + }, }, }, }, { loader: 'solid-loader', - options: { compiler: 'babel', decoratorVersion: 'legacy' }, + options: { + compiler: 'babel', + decoratorVersion: 'legacy', + }, }, ], }, @@ -170,8 +196,18 @@ export default { { test: /\.tsx?$/i, use: [ - { loader: 'builtin:swc-loader', options: { detectSyntax: 'auto' } }, - { loader: 'solid-loader', options: { scriptRegex: /\.tsx$/i } }, + { + loader: 'builtin:swc-loader', + options: { + detectSyntax: 'auto', + }, + }, + { + loader: 'solid-loader', + options: { + scriptRegex: /\.tsx$/i, + }, + }, ], }, ], @@ -191,7 +227,9 @@ export default { scheme: 'data', mimetype: 'text/javascript', loader: 'solid-loader', - options: { transformFilename: 'data-uri.jsx' }, + options: { + transformFilename: 'data-uri.jsx', + }, }, ], }, @@ -210,12 +248,16 @@ export default { test: /\.jsx$/i, enforce: 'pre', loader: 'solid-loader/refresh', - options: { granular: false }, + options: { + granular: false, + }, }, { test: /\.jsx$/i, loader: 'solid-loader', - options: { refresh: false }, + options: { + refresh: false, + }, }, ], },