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

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.37",
   "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);
 
@@ -558,6 +562,43 @@ module.exports = async function (inMeteor = {}, argv = {}) {
       ? path.resolve(process.cwd(), testEntry)
       : path.resolve(process.cwd(), buildContext, entryPath);
   const clientNameConfig = `[${(isTest && "test-") || ""}client-rspack]`;
+
+  // Default onListening provided by meteor-rspack. Kept as a named
+  // reference so we can detect a user-supplied override after merge
+  // and compose (run default first, then user's).
+  const meteorDefaultOnListening = function (devServer) {
+    if (!devServer) return;
+    const { host, port } = devServer.options;
+    const protocol =
+      devServer.options.server?.type === "https" ? "https" : "http";
+    const devServerUrl = `${protocol}://${host || "localhost"}:${port}`;
+    outputMeteorRspack({ devServerUrl });
+
+    // Windows-only: webpack-dev-server tracks accepted sockets
+    // but doesn't attach 'error'. On Windows, teardown of a
+    // closed proxy connection sends RST, producing an unhandled
+    // ECONNRESET that crashes the dev server. Unix peers send
+    // FIN and never hit this.
+    if (process.platform === "win32") {
+      const server = devServer.server;
+      if (!server || server.__meteorRspackErrorGuard) return;
+      server.__meteorRspackErrorGuard = true;
+
+      server.on("connection", (socket) => {
+        if (!socket || socket.__meteorRspackGuarded) return;
+        socket.__meteorRspackGuarded = true;
+        socket.on("error", (err) => {
+          if (err && err.code === "ECONNRESET") return;
+          console.warn(
+            `[meteor-rspack] dev server socket error: ${
+              err && (err.code || err.message)
+            }`
+          );
+        });
+      });
+    }
+  };
+
   // Base client config
   let clientConfig = {
     name: clientNameConfig,
@@ -650,17 +691,9 @@ module.exports = async function (inMeteor = {}, argv = {}) {
         ...(Meteor.isBlazeEnabled && { hot: false }),
         port: devServerPort,
         devMiddleware: {
-          writeToDisk: (filePath) =>
-            /\.(html)$/.test(filePath) || filePath.endsWith('sw.js'),
-        },
-        onListening(devServer) {
-          if (!devServer) return;
-          const { host, port } = devServer.options;
-          const protocol =
-            devServer.options.server?.type === "https" ? "https" : "http";
-          const devServerUrl = `${protocol}://${host || "localhost"}:${port}`;
-          outputMeteorRspack({ devServerUrl });
+          writeToDisk: createPersistCallback({ once: ['sw.js'], always: ['.html'] }),
         },
+        onListening: meteorDefaultOnListening,
       },
     }),
     ...merge(cacheStrategy, { experiments: { css: true } }),
@@ -713,7 +746,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
@@ -825,6 +873,23 @@ module.exports = async function (inMeteor = {}, argv = {}) {
     }
   }
 
+  // If the user or an override replaced devServer.onListening, compose
+  // so our default runs first (attaches the Windows socket guard and
+  // reports the dev server URL) and the user's hook runs second.
+  if (isClient && config.devServer) {
+    const finalOnListening = config.devServer.onListening;
+    if (
+      typeof finalOnListening === "function" &&
+      finalOnListening !== meteorDefaultOnListening
+    ) {
+      const userOnListening = finalOnListening;
+      config.devServer.onListening = function (devServer) {
+        meteorDefaultOnListening(devServer);
+        userOnListening(devServer);
+      };
+    }
+  }
+
   const shouldDisablePlugins = config?.disablePlugins != null;
   if (shouldDisablePlugins) {
     config = disablePlugins(config, config.disablePlugins);