add documentation for HtmlRspackPlugin configuration and others

2026-05-02 03:01:46 -04:00 · 2025-09-03 09:33:21 +02:00
parent 5467471a3c
commit 60dfd25e84
1 changed files with 103 additions and 10 deletions
--- a/v3-docs/docs/about/modern-build-stack/rspack-bundler-integration.md
+++ b/v3-docs/docs/about/modern-build-stack/rspack-bundler-integration.md
@@ -75,6 +75,22 @@ Attempts were made to reuse the existing `.meteor/local` cache context instead o
 Use `.meteor/local` or folders that suggest internals or hidden content (e.g., starting with a dot). These affect debug visibility, file watching, final compilation, and inclusion in the Cordova bundle.
 :::

+### Replace build plugins
+
+Meteor build plugins extend the Meteor bundler by letting you handle new file types and process them for the final app bundle. They’ve commonly handled HTML templating, style files for Less or SCSS, CoffeeScript, and more, since the system allows third-party customization.
+
+However, Meteor’s build system solves the same problems as other bundlers, including Rspack. Build plugins are largely deprecated in favor of Rspack alternatives. Some plugins may still be useful if they don’t act directly on app files and do something Meteor-specific that can be preserved.
+
+Among the compatible plugins:
+- zodern:types. Still compatible, automatically providing Meteor types for core and community packages.
+
+For others, please refer to the migration topics.
+- [CSS, Less, and SCSS](#css-less-and-scss) (when using less, fourseven:scss)
+- [Coffeescript](#coffeescript) (when using zodern:melte)
+- [Svelte](#svelte) (when using zodern:melte)
+
+Please report your plugin usage as [GitHub issues](https://github.com/meteor/meteor/issues?q=sort%3Aupdated-desc+is%3Aissue+is%3Aopen) or [forum posts](https://forums.meteor.com/), so we can suggest an Rspack alternative or assess compatibility.
+
 ## Custom `rspack.config.js`

 Meteor-Rspack projects can be customized using the `rspack.config.js` file, which is automatically available when installing the `rspack` package.
@@ -107,16 +123,18 @@ export default defineConfig(Meteor => {

 You can use flags to control the final configuration based on the environment. The available flags are passed in the `Meteor` parameter.

-| Flag            | Type    | Description                                        |
-| --------------- | ------- | -------------------------------------------------- |
-| `isDevelopment` | boolean | True when running in development mode              |
-| `isProduction`  | boolean | True when running in production mode               |
-| `isClient`      | boolean | True when building or running client code          |
-| `isServer`      | boolean | True when building or running server code          |
-| `isTest`        | boolean | True when running in test mode                     |
-| `isDebug`       | boolean | True when debug mode is enabled                    |
-| `isRun`         | boolean | True when running the project with `meteor run`    |
-| `isBuild`       | boolean | True when building the project with `meteor build` |
+| Flag               | Type     | Description                                               |
+| ------------------ | -------- |-----------------------------------------------------------|
+| `isDevelopment`    | boolean  | True when running in development mode                     |
+| `isProduction`     | boolean  | True when running in production mode                      |
+| `isClient`         | boolean  | True when building or running client code                 |
+| `isServer`         | boolean  | True when building or running server code                 |
+| `isTest`           | boolean  | True when running in test mode                            |
+| `isDebug`          | boolean  | True when debug mode is enabled                           |
+| `isRun`            | boolean  | True when running the project with `meteor run`           |
+| `isBuild`          | boolean  | True when building the project with `meteor build`        |
+| `swcConfigOptions` | object   | Project-level SWC config available for reusing            |
+| `HtmlRspackPlugin` | function | Custom HtmlRspackPlugin function for extending the config |

 Some configurations in the Rspack config are reserved for the Meteor-Rspack setup to work, such as Rspack options inside the `entry` and `output` objects. These will trigger warnings if modified. All other settings can be overridden, giving you the flexibility to make any setup compatible with the modern bundler.

@@ -286,6 +304,47 @@ Previous official support in the Meteor bundler was through [jorgenvatle:vite](h
 With Meteor-Rspack integration, you no longer need vite-related packages, so you should remove them from your project.
 :::

+### Coffeescript
+
+Meteor-Rspack supports CoffeeScript projects out of the box. To enable it, install the needed dependencies and add the configuration to Meteor’s rspack.config.js.
+
+[See the official Webpack and CoffeeScript integration guide](https://webpack.js.org/loaders/coffee-loader/#getting-started). Since Rspack is based on Webpack, the same setup applies.
+
+If you want to use SWC with CoffeeScript, combine `swc-loader` with `coffee-loader`.
+
+```bash
+npm install --save-dev coffeescript swc-loader coffee-loader
+```
+
+In your `rspack.config.js` you would add something like:
+
+``` javascript
+export default defineConfig(Meteor => {
+  return {
+    module: {
+      rules: [
+        {
+          test: /\.coffee$/i,
+          use: [
+            {
+              loader: 'swc-loader',
+              // perserve SWC config in the Meteor project level
+              options: Meteor.swcConfigOptions,
+            },
+            {
+              loader: 'coffee-loader',
+            },
+          ],
+        },
+      ],
+    },
+    resolve: {
+      extensions: ['.coffee'],
+    },
+  };
+});
+```
+
 ### Svelte

 Meteor-Rspack supports Svelte projects out of the box. To enable it, install the required dependencies and add the new configuration to Meteor’s `rspack.config.js` file.
@@ -306,6 +365,40 @@ Meteor-Rspack supports Tailwind projects out of the box. For details, check [the

 > Use `meteor create --tailwind` to start with a preconfigured Rspack Tailwind app.

+### HtmlRspackPlugin
+
+Meteor-Rspack includes its own HtmlRspackPlugin, enabled by default to attach chunks and assets to the HTML skeleton. Meteor then uses this HTML to generate the final index file.
+
+If you want to customize HtmlRspackPlugin, add it to your `rspack.config.js` file:
+
+```javascript
+export default defineConfig(Meteor => {
+  return {
+    plugins: [
+      Meteor.HtmlRspackPlugin({
+        meta: {
+          // Will generate: <meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no">
+          viewport: 'width=device-width, initial-scale=1, shrink-to-fit=no',
+          // Will generate: <meta name="theme-color" content="#4285f4">
+          'theme-color': '#4285f4',
+          // Will generate:  <meta http-equiv="Content-Security-Policy" content="default-src https:">
+          'Content-Security-Policy': {
+            'http-equiv': 'Content-Security-Policy',
+            content: 'default-src https:',
+          },
+        },
+      }),
+    ],
+  };
+});
+```
+
+This example adds meta tags to the HTML. For more options, see the [official Rspack and HTML integration guide](https://rspack.rs/plugins/rspack/html-rspack-plugin).
+
+:::warning
+You can still use HTML files near your Meteor client entry point to define customizations (for example, `./client/main.html` will generate correctly and apply the contents you add).
+:::
+
 ## Benefits

 Meteor–Rspack integration sends your app code to Rspack to use modern bundler features. Meteor then uses Rspack’s output to handle Meteor-specific tasks (like Atmosphere package compilation) and create the final bundle.