@meteorjs/rspack 1.1.0-beta.8 → 2.0.0

package/.claude/settings.local.json

@@ -0,0 +1,10 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(chmod +x:*)",
+      "Bash(bash:*)",
+      "Bash(npm install:*)",
+      "Bash(node:*)"
+    ]
+  }
+}

package/README.md

@@ -0,0 +1,142 @@
+# @meteorjs/rspack
+
+The default [Rspack](https://rspack.dev) configuration for Meteor applications. This package provides everything you need to bundle your Meteor app with Rspack out of the box: client and server builds, SWC transpilation, React/Blaze/Angular support, hot module replacement, asset management, and all the Meteor-specific wiring so you don't have to.
+
+When Meteor runs with the Rspack bundler enabled, this package is what generates the underlying Rspack configuration. It detects your project setup (TypeScript, React, Blaze, Angular), sets up the right loaders and plugins, defines `Meteor.isClient`/`Meteor.isServer` and friends, configures caching, and exposes a set of helpers you can use in your own `rspack.config.js` to customize the build without breaking Meteor integration.
+
+## What it provides
+
+- **Dual client/server builds** with the correct targets, externals, and output paths
+- **SWC-based transpilation** for JS/TS/JSX/TSX with automatic framework detection
+- **React Fast Refresh** in development when React is enabled
+- **Blaze template handling** via ignore-loader when Blaze is enabled
+- **Persistent filesystem caching** for fast rebuilds
+- **Asset externals and HTML generation** through custom Rspack plugins
+- **A `defineConfig` helper** that accepts a factory function receiving Meteor environment flags and build utilities
+- **Customizable config** via `rspack.config.js` in your project root, with safe merging that warns if you try to override reserved settings
+- **Automatic CSS delegation** when rspack is configured with CSS, Less, or SCSS loaders, Meteor automatically detects the handled extensions after the first compilation and stops processing those files itself in the entry folder context. No `.meteorignore` entries needed.
+
+## Installation
+
+[Rspack integration](https://docs.meteor.com/about/modern-build-stack/rspack-bundler-integration.html) is automatically managed by the rspack Atmosphere package.
+
+```bash
+meteor add rspack
+```
+
+By doing this, your Meteor app will automatically serve `@meteorjs/rspack` and the required `@rspack/cli`, `@rspack/core`, among others.
+
+## Usage
+
+In your project's `rspack.config.js`, use the `defineConfig` helper to customize the build. The factory function receives a `env` object with Meteor environment flags and helper utilities:
+
+```js
+const { defineConfig } = require('@meteorjs/rspack');
+
+module.exports = defineConfig((env, argv) => {
+  // env.isClient, env.isServer, env.isDevelopment, env.isProduction
+  // env.isReactEnabled, env.isBlazeEnabled, etc.
+
+  return {
+    // Your custom Rspack configuration here.
+    // It gets safely merged with the Meteor defaults.
+  };
+});
+```
+
+More information is available in the official docs: [Rspack Bundler Integration](https://docs.meteor.com/about/modern-build-stack/rspack-bundler-integration.html#custom-rspack-config-js).
+
+## Development
+
+### Install dependencies
+
+```bash
+npm install
+```
+
+### Version bumping
+
+Use `npm run bump` to update the version in `package.json` before publishing.
+
+```bash
+npm run bump -- <major|minor|patch> [--beta]
+```
+
+**Standard bumps** increment the version and remove any prerelease suffix:
+
+```bash
+npm run bump -- patch   # 1.0.1 -> 1.0.2
+npm run bump -- minor   # 1.0.1 -> 1.1.0
+npm run bump -- major   # 1.0.1 -> 2.0.0
+```
+
+**Beta bumps** append or increment a `-beta.N` prerelease suffix:
+
+```bash
+npm run bump -- patch --beta   # 1.0.1 -> 1.0.2-beta.0
+npm run bump -- patch --beta   # 1.0.2-beta.0 -> 1.0.2-beta.1
+npm run bump -- patch --beta   # 1.0.2-beta.1 -> 1.0.2-beta.2
+```
+
+If you change the bump level while on a beta, the base version updates and the beta counter resets:
+
+```bash
+npm run bump -- minor --beta   # 1.0.2-beta.2 -> 1.1.0-beta.0
+npm run bump -- major --beta   # 1.1.0-beta.0 -> 2.0.0-beta.0
+```
+
+### Publishing a beta release
+
+After bumping to a beta version, publish to the `beta` dist-tag:
+
+```bash
+npm run bump -- patch --beta
+npm run publish:beta
+```
+
+Users can then install the beta with:
+
+```bash
+npm install @meteorjs/rspack@beta
+```
+
+You can pass extra flags to `npm publish` through the script:
+
+```bash
+npm run publish:beta -- --dry-run
+```
+
+### Publishing an official release
+
+After bumping to a stable version, publish with the default `latest` tag:
+
+```bash
+npm run bump -- patch
+npm publish
+```
+
+### Typical workflows
+
+**Beta iteration**: ship multiple beta builds for the same upcoming patch:
+
+```bash
+npm run bump -- patch --beta    # 1.0.1 -> 1.0.2-beta.0
+npm run publish:beta
+# ... fix issues ...
+npm run bump -- patch --beta    # 1.0.2-beta.0 -> 1.0.2-beta.1
+npm run publish:beta
+```
+
+**Promote beta to stable**: once the beta is ready, bump to the stable version and publish:
+
+```bash
+npm run bump -- patch           # 1.0.2-beta.1 -> 1.0.3
+npm publish
+```
+
+**Direct stable release**: skip the beta phase entirely:
+
+```bash
+npm run bump -- minor           # 1.0.1 -> 1.1.0
+npm publish
+```

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,21 +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 Rspack SWC loader config.
+   * Extend the SWC loader config by smart-merging custom options on top of
+   * 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.
+   * @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>;
 
@@ -71,10 +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 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/localDependenciesHelpers.js

@@ -0,0 +1,184 @@
+const fs = require('fs');
+const path = require('path');
+
+/**
+ * Extract local file dependencies from a config file by parsing require/import statements using AST
+ * @param {string} configFilePath - Path to the config file to parse
+ * @returns {string[]} - Array of absolute paths to local dependencies
+ */
+function extractLocalDependencies(configFilePath) {
+  if (!configFilePath || !fs.existsSync(configFilePath)) {
+    return [];
+  }
+
+  try {
+    const swc = require('@swc/core');
+    const content = fs.readFileSync(configFilePath, 'utf-8');
+    const configDir = path.dirname(configFilePath);
+    const projectDir = process.cwd();
+    const dependencies = [];
+
+    // Parse the file into an AST
+    const ast = swc.parseSync(content, {
+      syntax: 'ecmascript',
+      dynamicImport: true,
+      target: 'es2020',
+    });
+
+    // Visit all nodes to find import/require statements
+    visitNode(ast, (node) => {
+      let modulePath = null;
+
+      // Handle require() calls: require('./plugin')
+      if (node.type === 'CallExpression' && 
+          node.callee.type === 'Identifier' && 
+          node.callee.value === 'require' &&
+          node.arguments.length > 0) {
+        const arg = node.arguments[0];
+        if (arg.expression?.type === 'StringLiteral') {
+          modulePath = arg.expression.value;
+        }
+      }
+
+      // Handle dynamic import() calls: import('./plugin')
+      if (node.type === 'CallExpression' &&
+          node.callee.type === 'Import' &&
+          node.arguments.length > 0) {
+        const arg = node.arguments[0];
+        if (arg.expression?.type === 'StringLiteral') {
+          modulePath = arg.expression.value;
+        }
+      }
+
+      // Handle static imports: import x from './plugin'
+      if (node.type === 'ImportDeclaration' && node.source?.type === 'StringLiteral') {
+        modulePath = node.source.value;
+      }
+
+      // Handle export re-exports: export * from './plugin'
+      if (node.type === 'ExportAllDeclaration' && node.source?.type === 'StringLiteral') {
+        modulePath = node.source.value;
+      }
+
+      // Handle named export re-exports: export { x } from './plugin'
+      if (node.type === 'ExportNamedDeclaration' && node.source?.type === 'StringLiteral') {
+        modulePath = node.source.value;
+      }
+
+      // If we found a module path, try to resolve it
+      if (modulePath) {
+        const resolvedPath = resolveLocalModule(modulePath, configDir, projectDir);
+        if (resolvedPath) {
+          dependencies.push(resolvedPath);
+        }
+      }
+    });
+
+    // Remove duplicates
+    return [...new Set(dependencies)];
+  } catch (error) {
+    console.warn('[Rspack Cache] Failed to parse config dependencies:', error.message);
+    return [];
+  }
+}
+
+/**
+ * Recursively visit all nodes in an AST
+ * @param {Object} node - AST node
+ * @param {Function} callback - Function to call for each node
+ */
+function visitNode(node, callback) {
+  if (!node || typeof node !== 'object') {
+    return;
+  }
+
+  callback(node);
+
+  // Visit all properties of the node
+  for (const key in node) {
+    if (Object.prototype.hasOwnProperty.call(node, key)) {
+      const value = node[key];
+      if (Array.isArray(value)) {
+        value.forEach(child => visitNode(child, callback));
+      } else if (typeof value === 'object') {
+        visitNode(value, callback);
+      }
+    }
+  }
+}
+
+/**
+ * Resolve a module path to an absolute path if it's a local file
+ * @param {string} modulePath - Module path from require/import statement
+ * @param {string} configDir - Directory containing the config file
+ * @param {string} projectDir - Project root directory
+ * @returns {string|null} - Resolved absolute path or null
+ */
+function resolveLocalModule(modulePath, configDir, projectDir) {
+  // Only process relative paths (starts with . or ..)
+  if (!modulePath.startsWith('.')) {
+    return null;
+  }
+
+  try {
+    let resolvedPath = path.resolve(configDir, modulePath);
+    const extensions = ['.js', '.mjs', '.cjs', '.ts', '.json'];
+
+    // If the path exists as-is, check if it's a directory needing index resolution
+    if (fs.existsSync(resolvedPath)) {
+      if (fs.statSync(resolvedPath).isDirectory()) {
+        let found = false;
+        for (const ext of extensions) {
+          const indexPath = path.join(resolvedPath, `index${ext}`);
+          if (fs.existsSync(indexPath)) {
+            resolvedPath = indexPath;
+            found = true;
+            break;
+          }
+        }
+        if (!found) {
+          return null;
+        }
+      }
+    } else {
+      // Try common extensions if file doesn't exist as-is
+      let found = false;
+
+      for (const ext of extensions) {
+        const pathWithExt = resolvedPath + ext;
+        if (fs.existsSync(pathWithExt)) {
+          resolvedPath = pathWithExt;
+          found = true;
+          break;
+        }
+      }
+
+      // If still not found, return null
+      if (!found) {
+        return null;
+      }
+    }
+
+    // Verify file is within project (not node_modules)
+    const resolvedReal = fs.realpathSync(resolvedPath);
+    const projectReal = fs.realpathSync(projectDir);
+
+    const isWithinProject = 
+      resolvedReal === projectReal ||
+      resolvedReal.startsWith(projectReal + path.sep);
+    const hasNodeModulesSegment = resolvedReal.split(path.sep).includes('node_modules');
+
+    if (isWithinProject && !hasNodeModulesSegment) {
+      return resolvedPath;
+    }
+  } catch (error) {
+    // Silently ignore resolution errors
+  }
+
+  return null;
+}
+
+module.exports = {
+  extractLocalDependencies,
+  resolveLocalModule,
+};

package/lib/meteorRspackConfigHelpers.js

@@ -0,0 +1,121 @@
+const path = require('path');
+const fs = require('fs');
+const { cleanOmittedPaths } = require("./mergeRulesSplitOverlap.js");
+const { mergeMeteorRspackFragments } = require("./meteorRspackConfigFactory.js");
+
+// Helper function to load and process config files
+async function loadAndProcessConfig(configPath, configType, Meteor, argv, disableWarnings) {
+  try {
+    // Load the config file
+    let config;
+    if (path.extname(configPath) === '.mjs') {
+      // For ESM modules, we need to use dynamic import
+      const fileUrl = `file://${configPath}`;
+      const module = await import(fileUrl);
+      config = module.default || module;
+    } else {
+      // For CommonJS modules, we can use require
+      config = require(configPath)?.default || require(configPath);
+    }
+
+    // Process the config
+    const rawConfig = typeof config === 'function' ? config(Meteor, argv) : config;
+    const resolvedConfig = await Promise.resolve(rawConfig);
+    const userConfig = resolvedConfig && '0' in resolvedConfig ? resolvedConfig[0] : resolvedConfig;
+
+    // Define omitted paths and warning function
+    const omitPaths = [
+      "name",
+      "target",
+      "entry",
+      "output.path",
+      "output.filename",
+      ...(Meteor.isServer ? ["optimization.splitChunks", "optimization.runtimeChunk"] : []),
+    ].filter(Boolean);
+
+    const warningFn = path => {
+      if (disableWarnings) return;
+      console.warn(
+        `[${configType}] Ignored custom "${path}" — reserved for Meteor-Rspack integration.`,
+      );
+    };
+
+    // Clean omitted paths and merge Meteor Rspack fragments
+    let nextConfig = cleanOmittedPaths(userConfig, {
+      omitPaths,
+      warningFn,
+    });
+    nextConfig = mergeMeteorRspackFragments(nextConfig);
+
+    return nextConfig;
+  } catch (error) {
+    console.error(`Error loading ${configType} from ${configPath}:`, error);
+    if (configType === 'rspack.config.js') {
+      throw error; // Only rethrow for project config
+    }
+    return null;
+  }
+}
+
+/**
+ * Loads both the user's Rspack configuration and its potential override.
+ *
+ * @param {string|undefined} projectConfigPath
+ * @param {object} Meteor
+ * @param {object} argv
+ * @returns {Promise<{ nextUserConfig: object|null, nextOverrideConfig: object|null }>}
+ */
+async function loadUserAndOverrideConfig(projectConfigPath, Meteor, argv) {
+  let nextUserConfig = null;
+  let nextOverrideConfig = null;
+
+  const projectDir = process.cwd();
+  const isMeteorPackageConfig = projectDir.includes("/packages/rspack");
+
+  if (projectConfigPath) {
+    const configDir = path.dirname(projectConfigPath);
+    const configFileName = path.basename(projectConfigPath);
+    const configExt = path.extname(configFileName);
+    const configNameWithoutExt = configFileName.replace(configExt, '');
+    const configNameFull = `${configNameWithoutExt}.override${configExt}`;
+    const overrideConfigPath = path.join(configDir, configNameFull);
+
+    if (fs.existsSync(overrideConfigPath)) {
+      nextOverrideConfig = await loadAndProcessConfig(
+        overrideConfigPath,
+        configNameFull,
+        Meteor,
+        argv,
+        Meteor.isAngularEnabled
+      );
+    }
+
+    if (fs.existsSync(projectConfigPath) && !isMeteorPackageConfig) {
+      // Check if there's a .mjs or .cjs version of the config file
+      const mjsConfigPath = projectConfigPath.replace(/\.js$/, '.mjs');
+      const cjsConfigPath = projectConfigPath.replace(/\.js$/, '.cjs');
+
+      let projectConfigPathToUse = projectConfigPath;
+      if (fs.existsSync(mjsConfigPath)) {
+        projectConfigPathToUse = mjsConfigPath;
+      } else if (fs.existsSync(cjsConfigPath)) {
+        projectConfigPathToUse = cjsConfigPath;
+      }
+
+      nextUserConfig = await loadAndProcessConfig(
+        projectConfigPathToUse,
+        'rspack.config.js',
+        Meteor,
+        argv,
+        Meteor.isAngularEnabled
+      );
+    }
+  }
+
+  return { nextUserConfig, nextOverrideConfig };
+}
+
+module.exports = {
+  loadAndProcessConfig,
+  loadUserAndOverrideConfig,
+};