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.

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 @@ -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