diff --git a/README.md b/README.md index 10757ae..8ab7bbd 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.
@@ -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
@@ -33,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',
],
},
@@ -42,110 +54,215 @@ 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.
-
-```js
-{
- test: /\.[mc]?[jt]sx$/i,
- enforce: 'pre',
- exclude: /node_modules/,
- dependency: { not: 'url' },
- resourceQuery: { not: /[?&]raw(?:&|=|$)/ },
- with: { type: { not: 'text' } },
- loader: 'solid-loader/refresh',
-}
-```
+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
-If the client will hydrate server-rendered HTML, enable `hydratable` in both builds. Set `solid.generate` to match the output each build needs.
+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.
-| Build | Compiler options |
-| ---------------------------- | --------------------------------------- |
-| Server | `{ generate: 'ssr', hydratable: true }` |
-| Client hydrating server HTML | `{ generate: 'dom', hydratable: true }` |
+The [server configuration](#solid) also lets the Solid runtime load hydration modules by URL.
-Add this rule so the Solid runtime can load hydration modules by URL.
+## Options
-```js
-{
- descriptionData: { name: /^@solidjs\/web$/ },
- parser: { importDynamic: false },
-}
-```
+Set loader options in `module.rules` in your `rspack.config.ts`. The main loader exports the `SolidLoaderOptions` type, and `solid-loader/refresh` exports `SolidRefreshLoaderOptions`.
-## Options
+### compiler
-Pass options to the loader in the rule’s `use` array. This example selects the Babel backend.
+The loader uses Solid’s native compiler by default (`'native'`). Set `compiler` to `'babel'` to compile JSX with `@solidjs/babel-plugin`.
```ts
-const jsxRule = {
- test: /\.[mc]?[jt]sx$/i,
- use: [
- { loader: 'builtin:swc-loader', options: { detectSyntax: 'auto' } },
- { loader: 'solid-loader', options: { compiler: 'babel' } },
- ],
+export default {
+ module: {
+ rules: [
+ {
+ test: /\.jsx$/i,
+ loader: 'solid-loader',
+ options: {
+ compiler: 'babel',
+ },
+ },
+ ],
+ },
};
```
-For typed configurations, import `SolidLoaderOptions`, `SolidCompiler`, or `SolidPresetOptions` from `solid-loader`, and `SolidRefreshLoaderOptions` from `solid-loader/refresh`.
-
-### compiler
-
-- **Type:** `'native' | 'babel'`
-- **Default:** `'native'`
-
-Selects the Solid JSX compiler. The default uses `@solidjs/compiler`. Set this to `'babel'` to compile with `@solidjs/babel-plugin`.
-
### 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
+export default {
+ module: {
+ rules: [
+ {
+ test: /\.jsx$/i,
+ loader: 'solid-loader',
+ 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
+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
-- **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
+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
-- **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
+export default {
+ module: {
+ rules: [
+ {
+ test: /\.tsx?$/i,
+ use: [
+ {
+ loader: 'builtin:swc-loader',
+ options: {
+ detectSyntax: 'auto',
+ },
+ },
+ {
+ loader: 'solid-loader',
+ 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
+export default {
+ module: {
+ rules: [
+ {
+ scheme: 'data',
+ mimetype: 'text/javascript',
+ loader: 'solid-loader',
+ 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
+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