@meteorjs/rspack 1.1.0-beta.35 → 1.1.0-beta.36

package/index.d.ts

@@ -29,12 +29,14 @@ type MeteorEnv = Record<string, any> & {
    * A function that creates an instance of HtmlRspackPlugin with default options.
    * @param options - Optional configuration options that will be merged with defaults
    * @returns An instance of HtmlRspackPlugin
+   * @example Meteor.HtmlRspackPlugin({ title: 'My App' })
    */
   HtmlRspackPlugin: (options?: HtmlRspackPluginOptions) => HtmlRspackPlugin;
   /**
    * Wrap externals for Meteor runtime.
    * @param deps - Package names or module IDs
    * @returns A config object with externals configuration
+   * @example ...Meteor.compileWithMeteor(['sharp', 'thread-stream'])
    */
   compileWithMeteor: (deps: RuleSetConditions) => Record<string, object>;
   /**
@@ -42,6 +44,7 @@ type MeteorEnv = Record<string, any> & {
    * @param deps - Package names to include in SWC loader
    * @param options - Optional configuration options
    * @returns A config object with module rules configuration
+   * @example ...Meteor.compileWithRspack(['grubba-rpc', 'zod'])
    */
   compileWithRspack: (deps: RuleSetConditions, options?: SwcLoaderOptions) => Record<string, object>;
   /**
@@ -49,32 +52,35 @@ type MeteorEnv = Record<string, any> & {
    * @param enabled - Whether to enable caching
    * @param cacheConfig - Optional cache configuration
    * @returns A config object with cache configuration
+   * @example ...Meteor.setCache(false)
    */
   setCache: (enabled: boolean | 'memory') => Record<string, object>;
   /**
    * Enable Rspack split vendor chunk.
    * @returns A config object with optimization configuration
+   * @example ...Meteor.splitVendorChunk()
    */
   splitVendorChunk: () => Record<string, object>;
   /**
    * Extend the SWC loader config by smart-merging custom options on top of
-   * Meteor's defaults.  Only the properties you specify are overridden;
+   * Meteor's defaults. Only the properties you specify are overridden;
    * everything else is preserved.
    * @param swcConfig - SWC loader options to merge with defaults
    * @returns A config object with SWC loader config
+   * @example ...Meteor.extendSwcConfig({ jsc: { parser: { decorators: true } } })
    */
   extendSwcConfig: (swcConfig: SwcLoaderOptions) => Record<string, object>;
   /**
    * Replace the SWC loader config entirely, discarding Meteor's defaults.
-   * Use this when you need full control over SWC options and don't want any
-   * automatic merging with Meteor's built-in configuration.
    * @param swcConfig - Complete SWC loader options (replaces defaults)
    * @returns A config object with SWC loader config
+   * @example ...Meteor.replaceSwcConfig({ jsc: { target: 'es2020' } })
    */
   replaceSwcConfig: (swcConfig: SwcLoaderOptions) => Record<string, object>;
   /**
    * Extend Rspack configs.
    * @returns A config object with merged configs
+   * @example ...Meteor.extendConfig(configA, configB)
    */
   extendConfig: (...configs: Record<string, object>[]) => Record<string, object>;
 
@@ -82,16 +88,43 @@ type MeteorEnv = Record<string, any> & {
    * Remove plugins from a Rspack config by name, RegExp, predicate, or array of them.
    * @param matchers - String, RegExp, function, or array of them to match plugin names
    * @returns The modified config object
+   * @example ...Meteor.disablePlugins(['DefinePlugin', /HtmlRspack/])
    */
   disablePlugins: (
     matchers: string | RegExp | ((plugin: any, index: number) => boolean) | Array<string | RegExp | ((plugin: any, index: number) => boolean)>
   ) => Record<string, any>;
   /**
    * Omit `Meteor.isDevelopment` and `Meteor.isProduction` from the DefinePlugin so
-   * the bundle is not tied to a specific Meteor environment (portable / isomorphic builds).
+   * the bundle is not tied to a specific Meteor environment (portable builds).
    * @returns A config fragment with `meteor.enablePortableBuild: true`
+   * @example ...Meteor.enablePortableBuild()
    */
   enablePortableBuild: () => Record<string, any>;
+  /**
+   * Persist build-output files to disk during development.
+   * HTML files are always persisted automatically.
+   *
+   * Matchers: `string` (endsWith), `RegExp`, or `(filePath) => boolean`.
+   * Array form defaults to `always`. Object form supports `once` and `always`.
+   * - `always` — written on every build (default)
+   * - `once` — first build only (e.g. service workers)
+   *
+   * @param matchers - Array or `{ once?, always? }` of matchers
+   * @returns A config fragment with `devServer.devMiddleware.writeToDisk`
+   *
+   * @example
+   * ...Meteor.persistDevFiles({ once: ['sw.js'], always: ['manifest.json'] })
+   */
+  persistDevFiles: (
+    matchers:
+      | (string | RegExp | ((filePath: string) => boolean))[]
+      | {
+          /** Files written on the first build only. */
+          once?: (string | RegExp | ((filePath: string) => boolean))[];
+          /** Files written on every build. */
+          always?: (string | RegExp | ((filePath: string) => boolean))[];
+        }
+  ) => Record<string, object>;
 }
 
 export type ConfigFactory = (

package/lib/meteorRspackHelpers.js

@@ -244,6 +244,92 @@ function disablePlugins(config, matchers) {
   return config;
 }
 
+/**
+ * Create a `writeToDisk` callback that persists specific files to disk
+ * during development.
+ *
+ * Accepts an array (defaults to "always" strategy) or an object with
+ * `once` and/or `always` keys for mixed strategies.
+ *
+ * Matchers can be:
+ * - **string**: matched with `endsWith` (e.g. `'sw.js'`, `'.html'`)
+ * - **RegExp**: tested against the full file path
+ * - **function**: `(filePath: string) => boolean`
+ *
+ * Strategies:
+ * - `always`: Write on every build (default). Use for files that should
+ *             always reflect the latest build output.
+ * - `once`:   Write on the first build only. Skipped on HMR rebuilds to
+ *             avoid triggering service worker re-registration or file
+ *             watcher restarts.
+ *
+ * @example
+ * // Simple: array defaults to "always"
+ * ...Meteor.persistDevFiles(['manifest.json'])
+ *
+ * // Mixed strategies with strings, regex, and functions
+ * ...Meteor.persistDevFiles({
+ *   once: ['sw.js', /\.worker\.js$/],
+ *   always: ['manifest.json', (filePath) => filePath.includes('/custom/')],
+ * })
+ *
+ * @param {(string|RegExp|Function)[] | { once?: (string|RegExp|Function)[], always?: (string|RegExp|Function)[] }} matchers
+ * @returns {Record<string, object>} config fragment with devServer.devMiddleware.writeToDisk
+ */
+/**
+ * Build the writeToDisk callback from matchers.
+ * Shared by persistDevFiles (fragment) and internal usage (direct).
+ * @private
+ */
+function createPersistCallback(matchers) {
+  const once = [];
+  const always = [];
+
+  if (Array.isArray(matchers)) {
+    always.push(...matchers);
+  } else {
+    if (matchers.once) once.push(...matchers.once);
+    if (matchers.always) always.push(...matchers.always);
+  }
+
+  // HTML files are always persisted, Meteor's web server relies on them
+  if (!always.includes('.html')) {
+    always.push('.html');
+  }
+
+  const match = (filePath, pattern) => {
+    if (typeof pattern === 'function') return pattern(filePath);
+    if (typeof pattern === 'string') return filePath.endsWith(pattern);
+    return pattern.test(filePath);
+  };
+
+  const written = new Set();
+
+  return (filePath) => {
+    for (const pattern of always) {
+      if (match(filePath, pattern)) return true;
+    }
+    for (let i = 0; i < once.length; i++) {
+      if (match(filePath, once[i])) {
+        if (written.has(i)) return false;
+        written.add(i);
+        return true;
+      }
+    }
+    return false;
+  };
+}
+
+function persistDevFiles(matchers) {
+  return prepareMeteorRspackConfig({
+    devServer: {
+      devMiddleware: {
+        writeToDisk: createPersistCallback(matchers),
+      },
+    },
+  });
+}
+
 function outputMeteorRspack(data) {
   const jsonString = JSON.stringify(data);
   const output = `[Meteor-Rspack]${jsonString}[/Meteor-Rspack]`;
@@ -261,4 +347,6 @@ module.exports = {
   disablePlugins,
   outputMeteorRspack,
   enablePortableBuild,
+  persistDevFiles,
+  createPersistCallback,
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@meteorjs/rspack",
-  "version": "1.1.0-beta.35",
+  "version": "1.1.0-beta.36",
   "description": "Configuration logic for using Rspack in Meteor projects",
   "main": "index.js",
   "type": "commonjs",

package/rspack.config.js

@@ -24,6 +24,8 @@ const {
   disablePlugins,
   outputMeteorRspack,
   enablePortableBuild,
+  persistDevFiles,
+  createPersistCallback,
 } = require('./lib/meteorRspackHelpers.js');
 const { loadUserAndOverrideConfig } = require('./lib/meteorRspackConfigHelpers.js');
 const { prepareMeteorRspackConfig } = require("./lib/meteorRspackConfigFactory");
@@ -348,6 +350,7 @@ module.exports = async function (inMeteor = {}, argv = {}) {
       disablePlugins: matchers,
     });
   Meteor.enablePortableBuild = () => enablePortableBuild();
+  Meteor.persistDevFiles = (matchers) => persistDevFiles(matchers);
 
   // Add HtmlRspackPlugin function to Meteor
   Meteor.HtmlRspackPlugin = (options = {}) => {
@@ -416,6 +419,7 @@ module.exports = async function (inMeteor = {}, argv = {}) {
   const clientOutputDir = path.resolve(projectDir, "public");
   const serverOutputDir = path.resolve(projectDir, "private");
 
+
   // Get Meteor ignore entries
   const meteorIgnoreEntries = getMeteorIgnoreEntries(projectDir);
 
@@ -650,8 +654,7 @@ module.exports = async function (inMeteor = {}, argv = {}) {
         ...(Meteor.isBlazeEnabled && { hot: false }),
         port: devServerPort,
         devMiddleware: {
-          writeToDisk: (filePath) =>
-            /\.(html)$/.test(filePath) || filePath.endsWith('sw.js'),
+          writeToDisk: createPersistCallback({ once: ['sw.js'], always: ['.html'] }),
         },
         onListening(devServer) {
           if (!devServer) return;
@@ -713,7 +716,22 @@ module.exports = async function (inMeteor = {}, argv = {}) {
       runtimeChunk: false,
     },
     module: {
-      rules: [swcConfigRule, ...extraRules],
+      rules: [
+        swcConfigRule,
+        // Mirror the client rule: ignore .html so rspack doesn't try to
+        // parse them as JavaScript. Meteor's template compiler handles
+        // .html files separately, and RequireExternalsPlugin below wires
+        // the imports to Meteor's module system.
+        ...(Meteor.isBlazeEnabled
+          ? [
+              {
+                test: /\.html$/i,
+                loader: 'ignore-loader',
+              },
+            ]
+          : []),
+        ...extraRules,
+      ],
       parser: {
         javascript: {
           // Dynamic imports on the server are treated as bundled in the same chunk