shakapacker 9.3.0.beta.6 → 9.3.0

data/docs/rspack_migration_guide.md

@@ -11,7 +11,9 @@
   - [Server-Side Rendering (SSR) Considerations](#server-side-rendering-ssr-considerations)
 - [Key Differences from Webpack](#key-differences-from-webpack)
 - [Migration Steps](#migration-steps)
+- [Build Verification](#build-verification)
 - [Configuration Best Practices](#configuration-best-practices)
+- [Common Migration Issues](#common-migration-issues)
 - [Common Issues and Solutions](#common-issues-and-solutions)
 - [Performance Tips](#performance-tips)
 - [Debugging Configuration](#debugging-configuration)
@@ -312,6 +314,73 @@ bin/shakapacker --mode production
 - [ ] Deploy to staging
 - [ ] Monitor performance improvements
 
+## Build Verification
+
+After completing your migration, verify that everything works correctly:
+
+### Basic Build Verification
+
+```bash
+# Clean previous build artifacts
+rm -rf public/packs public/packs-test
+
+# Test development build
+bin/shakapacker
+
+# Test production build
+RAILS_ENV=production bin/shakapacker
+
+# Verify assets were generated
+ls -la public/packs/
+```
+
+### SSR Build Verification
+
+If your application uses Server-Side Rendering, perform these additional checks:
+
+```bash
+# 1. Verify server bundle was created
+ls -la public/packs/*-server-bundle.js
+
+# 2. Test SSR rendering in Rails console
+bundle exec rails console
+# In console:
+ReactOnRails::ServerRenderingPool.reset_pool
+# Then visit a page that uses SSR and check for errors
+
+# 3. Run full test suite (watch for SSR-related failures)
+bundle exec rspec
+
+# 4. Check for CSS extraction issues in SSR
+# Look for "Cannot read properties of undefined" errors in tests
+# or intermittent test failures related to styling
+```
+
+### Common Verification Issues
+
+**Silent SSR failures**: If your SSR pages render without errors but components appear unstyled or with missing data, check:
+
+- Server bundle is being generated correctly
+- CSS extraction is disabled for server bundle (see [Common Migration Issues](#common-migration-issues))
+- React runtime configuration is compatible with your SSR framework
+
+**Error patterns to watch for**:
+
+- `Cannot read properties of undefined (reading 'className')` - CSS Modules configuration issue
+- `Invalid call to renderToString` - React runtime compatibility issue
+- `Module not found: Can't resolve './Module.bs.js'` - File extension resolution issue
+- Intermittent/flaky tests - CSS extraction leaking into server bundle
+
+### Testing Strategy for SSR
+
+For applications with SSR, follow this verification order:
+
+1. Test client-only pages first (verify basic Rspack build works)
+2. Test SSR pages without CSS modules (verify SSR configuration)
+3. Test SSR pages with CSS modules (verify CSS extraction + SSR work together)
+4. Run full test suite multiple times to catch flaky tests
+5. Test in production mode (some issues only appear with minification)
+
 ## Configuration Best Practices
 
 ### Configuration Organization
@@ -390,6 +459,173 @@ When upgrading to Shakapacker 9 with Rspack:
 4. **Check Node version compatibility**: Verify your Node version meets all dependency requirements
 5. **Don't make empty commits**: If CI fails but local passes, investigate the root cause - don't try to "trigger CI re-run" with empty commits
 
+## Common Migration Issues
+
+This section highlights the most critical configuration issues that cause build failures during webpack-to-Rspack migration. These issues are especially important for applications using Server-Side Rendering (SSR), CSS Modules, or non-standard file extensions.
+
+### 1. SWC React Runtime for SSR (CRITICAL for React on Rails)
+
+**Problem**: React on Rails SSR detection expects specific function signatures that may not work with SWC's automatic React runtime.
+
+**Symptoms**:
+
+- Error: `Invalid call to renderToString. Possibly you have a renderFunction...`
+- SSR pages fail to render or render without React hydration
+
+**Solution**: Configure SWC to use classic React runtime instead of automatic:
+
+```javascript
+// config/swc.config.js
+const customConfig = {
+  options: {
+    jsc: {
+      transform: {
+        react: {
+          runtime: "classic", // Use 'classic' instead of 'automatic' for SSR
+          refresh: env.isDevelopment && env.runningWebpackDevServer
+        }
+      }
+    }
+  }
+}
+```
+
+**Why this matters**: The automatic runtime changes how React imports work (`import { jsx as _jsx }` vs `import React`), which breaks React on Rails' SSR function detection logic. This is a silent failure that only manifests at runtime.
+
+**Implementation checklist for SSR users**:
+
+- [ ] Locate your SWC configuration file (typically `config/swc.config.js`)
+- [ ] Change `runtime: 'automatic'` to `runtime: 'classic'`
+- [ ] Test SSR rendering in development and production modes
+- [ ] Verify React hydration works correctly on client side
+- [ ] Run full test suite to catch any related issues
+
+### 2. CSS Modules Configuration for Server Bundles (CRITICAL for SSR + CSS Modules)
+
+**Problem**: When configuring server bundles, you must preserve Shakapacker 9's CSS Modules settings (`namedExport: true`) while adding SSR-specific settings. Simply setting `exportOnlyLocals: true` will override the base configuration and break CSS imports.
+
+**Symptoms**:
+
+- Error: `export 'default' (imported as 'css') was not found`
+- CSS classes return undefined in SSR
+- Client-side CSS works but SSR fails
+- Intermittent/flaky test failures
+
+**Solution**: Use spread operator to merge CSS Modules options instead of replacing them:
+
+```javascript
+// config/webpack/serverWebpackConfig.js
+if (cssLoader && cssLoader.options && cssLoader.options.modules) {
+  // ✅ CORRECT - Preserves namedExport and other settings
+  cssLoader.options.modules = {
+    ...cssLoader.options.modules,
+    exportOnlyLocals: true
+  }
+
+  // ❌ INCORRECT - Overwrites all settings
+  // cssLoader.options.modules.exportOnlyLocals = true
+}
+```
+
+**Why this matters**: Shakapacker 9 changed the default CSS Modules configuration to use named exports. If you only set `exportOnlyLocals: true` without preserving the base config, you'll lose the `namedExport: true` setting, causing import/export mismatches between client and server bundles.
+
+**Related configuration**: You must also filter out CSS extraction loaders in server bundles:
+
+```javascript
+// config/webpack/serverWebpackConfig.js
+rule.use = rule.use.filter((item) => {
+  let testValue
+  if (typeof item === "string") {
+    testValue = item
+  } else if (typeof item.loader === "string") {
+    testValue = item.loader
+  }
+  // Handle both Webpack and Rspack CSS extract loaders
+  return !(
+    testValue?.match(/mini-css-extract-plugin/) ||
+    testValue?.includes("cssExtractLoader") || // Rspack uses this path
+    testValue === "style-loader"
+  )
+})
+```
+
+**Implementation checklist for SSR + CSS Modules users**:
+
+- [ ] Update server bundle config to use spread operator for CSS Modules options
+- [ ] Ensure CSS extraction loaders are filtered for both webpack and Rspack paths
+- [ ] Test SSR pages with CSS Modules imports
+- [ ] Verify CSS classes are defined (not undefined) during SSR
+- [ ] Run tests multiple times to catch flaky failures
+
+### 3. ReScript File Resolution (CRITICAL for ReScript users)
+
+**Problem**: Rspack requires explicit configuration to resolve `.bs.js` extensions (ReScript compiled output), while webpack handled this automatically.
+
+**Symptoms**:
+
+- Error: `Module not found: Can't resolve './Module.bs.js'`
+- ReScript modules fail to import
+- Build fails with missing module errors
+
+**Solution**: Add `.bs.js` to resolve extensions:
+
+```javascript
+// config/webpack/webpack.config.js (works for both webpack and rspack)
+const commonOptions = {
+  resolve: {
+    extensions: [".css", ".ts", ".tsx", ".bs.js"] // Add .bs.js for ReScript
+  }
+}
+
+module.exports = merge({}, baseConfig, commonOptions)
+```
+
+**Why this matters**: ReScript compiles `.res` source files to `.bs.js` JavaScript files. If your bundler can't resolve these extensions, all ReScript imports will fail, even though the compiled files exist.
+
+**Additional consideration - Missing compiled files**: Some ReScript npm packages ship only `.res` source files without compiled `.bs.js` files. If you encounter this, use `patch-package` to fix the dependency's `bsconfig.json` (see detailed solution in [Common Issues and Solutions](#issue-rescript-dependencies-missing-compiled-files)).
+
+**Implementation checklist for ReScript users**:
+
+- [ ] Add `.bs.js` to resolve extensions in webpack/rspack config
+- [ ] Verify all ReScript modules can be imported
+- [ ] Check if any ReScript dependencies are missing compiled files
+- [ ] If needed, patch broken dependencies with `patch-package`
+- [ ] Test build with all ReScript code paths
+
+### 4. Build Verification Steps (IMPORTANT for all migrations)
+
+**Problem**: The migration documentation lacked practical verification procedures, leaving developers without guidance on testing SSR functionality or identifying configuration errors.
+
+**Solution**: Follow the comprehensive verification steps in the [Build Verification](#build-verification) section above, which includes:
+
+- Basic build verification commands
+- SSR-specific testing procedures
+- Error pattern identification
+- Testing strategy for SSR applications
+
+**Why this matters**: Silent SSR failures and configuration issues often only manifest in specific scenarios (production mode, certain page types, race conditions in tests). Without systematic verification, these issues may slip into production.
+
+**Implementation checklist for all users**:
+
+- [ ] Clean build artifacts before testing
+- [ ] Test both development and production builds
+- [ ] Verify generated assets in `public/packs/`
+- [ ] For SSR: verify server bundle generation
+- [ ] For SSR: test rendering in Rails console
+- [ ] Run full test suite multiple times
+- [ ] Check for error patterns listed in Build Verification
+
+### Configuration Differences: webpack vs Rspack Summary
+
+Quick reference for the key differences that cause migration issues:
+
+| Area                       | Webpack                   | Rspack                              | Migration Action                            |
+| -------------------------- | ------------------------- | ----------------------------------- | ------------------------------------------- |
+| CSS Extraction Loader Path | `mini-css-extract-plugin` | `cssExtractLoader.js`               | Filter both paths in SSR config             |
+| React Runtime (SSR)        | Works with both           | Classic required for React on Rails | Use `runtime: 'classic'`                    |
+| ReScript Extensions        | Auto-resolves `.bs.js`    | Requires explicit config            | Add to `resolve.extensions`                 |
+| CSS Modules Default        | `namedExport: true` (v9+) | Same                                | Preserve with spread operator in SSR config |
+
 ## Common Issues and Solutions
 
 ### Issue: CSS Modules Returning Undefined (CRITICAL)
@@ -601,13 +837,13 @@ To compare your webpack and rspack configurations during migration:
 
 ```bash
 # Export webpack configs before switching
-bin/export-bundler-config --doctor
+bin/shakapacker-config --doctor
 
 # Switch to rspack
 rails shakapacker:switch_bundler rspack --install-deps
 
 # Export rspack configs to compare
-bin/export-bundler-config --doctor
+bin/shakapacker-config --doctor
 
 # Compare the files in shakapacker-config-exports/
 diff shakapacker-config-exports/webpack-production-client.yaml \

data/docs/troubleshooting.md

@@ -21,7 +21,7 @@ If you're experiencing FOUC where content briefly appears unstyled before CSS lo
 
 4. You can also pass additional options to the command to run the webpack-dev-server and start the webpack-dev-server with the option `--debug-shakapacker`
 
-5. **Export your full webpack/rspack configuration for analysis**: Use the `bin/export-bundler-config` utility to export your complete resolved configuration. This is especially helpful for:
+5. **Export your full webpack/rspack configuration for analysis**: Use the `bin/shakapacker-config` utility to export your complete resolved configuration. This is especially helpful for:
    - **Migrations**: Comparing configurations before and after migrating between webpack and rspack, or between different Shakapacker versions
    - **Debugging**: Inspecting the exact configuration webpack/rspack is using, including all merged settings
    - **AI Analysis**: Uploading the exported config to ChatGPT or other AI tools for troubleshooting
@@ -35,7 +35,7 @@ If you're experiencing FOUC where content briefly appears unstyled before CSS lo
    rake shakapacker:binstubs
 
    # Export EVERYTHING for troubleshooting (dev + prod, annotated YAML)
-   bin/export-bundler-config --doctor
+   bin/shakapacker-config --doctor
    # Creates: webpack-development-client.yaml, webpack-development-server.yaml,
    #          webpack-production-client.yaml, webpack-production-server.yaml
    ```
@@ -44,28 +44,28 @@ If you're experiencing FOUC where content briefly appears unstyled before CSS lo
 
    ```bash
    # Save current environment configs with auto-generated names
-   bin/export-bundler-config --save
+   bin/shakapacker-config --save
    # Creates: webpack-development-client.yaml, webpack-development-server.yaml
 
    # Save to specific directory
-   bin/export-bundler-config --save --save-dir=./debug-configs
+   bin/shakapacker-config --save --save-dir=./debug-configs
 
    # Export only client config for production
-   bin/export-bundler-config --save --env=production --client-only
+   bin/shakapacker-config --save --env=production --client-only
    # Creates: webpack-production-client.yaml
 
    # Compare development vs production configs
-   bin/export-bundler-config --save --save-dir=./configs
+   bin/shakapacker-config --save --save-dir=./configs
    diff configs/webpack-development-client.yaml configs/webpack-production-client.yaml
 
    # View config in terminal (no files created)
-   bin/export-bundler-config
+   bin/shakapacker-config
 
    # Export without inline documentation annotations
-   bin/export-bundler-config --save --no-annotate
+   bin/shakapacker-config --save --no-annotate
 
    # Export in JSON format for programmatic analysis
-   bin/export-bundler-config --save --format=json
+   bin/shakapacker-config --save --format=json
    ```
 
    **Config files are automatically named:** `{bundler}-{env}-{type}.{ext}`
@@ -73,9 +73,9 @@ If you're experiencing FOUC where content briefly appears unstyled before CSS lo
    - YAML format includes inline documentation explaining each config key
    - Separate files for client and server bundles (cleaner than combined)
 
-   See `bin/export-bundler-config --help` for all available options.
+   See `bin/shakapacker-config --help` for all available options.
 
-6. **Validate your webpack/rspack builds**: Use `bin/export-bundler-config --validate` to test that all your build configurations compile successfully. This is especially useful for:
+6. **Validate your webpack/rspack builds**: Use `bin/shakapacker-config --validate` to test that all your build configurations compile successfully. This is especially useful for:
    - **CI/CD pipelines**: Catch configuration errors before deployment
    - **Migration testing**: Verify builds work after upgrading webpack, rspack, or Shakapacker
    - **Multi-environment testing**: Ensure all build configurations (dev, prod, HMR) compile correctly
@@ -84,13 +84,13 @@ If you're experiencing FOUC where content briefly appears unstyled before CSS lo
 
    ```bash
    # Validate all builds defined in .bundler-config.yml
-   bin/export-bundler-config --validate
+   bin/shakapacker-config --validate
 
    # Validate with full output logs (shows all webpack/rspack compilation output)
-   bin/export-bundler-config --validate --verbose
+   bin/shakapacker-config --validate --verbose
 
    # Validate a specific build
-   bin/export-bundler-config --validate-build=dev-hmr
+   bin/shakapacker-config --validate-build=dev-hmr
    ```
 
    **Verbose Mode:**
@@ -108,13 +108,13 @@ If you're experiencing FOUC where content briefly appears unstyled before CSS lo
 
    ```bash
    # Create a .bundler-config.yml file with example builds
-   bin/export-bundler-config --init
+   bin/shakapacker-config --init
 
    # List all available builds
-   bin/export-bundler-config --list-builds
+   bin/shakapacker-config --list-builds
 
    # Validate all builds
-   bin/export-bundler-config --validate
+   bin/shakapacker-config --validate
    ```
 
    **Advanced options:**
@@ -177,9 +177,9 @@ If you're experiencing FOUC where content briefly appears unstyled before CSS lo
    💡 Debugging Tips:
       To get more details, run individual builds with --verbose:
 
-      bin/export-bundler-config --validate-build prod --verbose
+      bin/shakapacker-config --validate-build prod --verbose
 
-      Or validate all builds with full output: bin/export-bundler-config --validate --verbose
+      Or validate all builds with full output: bin/shakapacker-config --validate --verbose
    ================================================================================
    ```
 
@@ -189,13 +189,13 @@ If you're experiencing FOUC where content briefly appears unstyled before CSS lo
    1. **Run a specific build with verbose output** to see full webpack/rspack logs:
 
       ```bash
-      bin/export-bundler-config --validate-build prod --verbose
+      bin/shakapacker-config --validate-build prod --verbose
       ```
 
    2. **Validate all builds with verbose output** to see everything:
 
       ```bash
-      bin/export-bundler-config --validate --verbose
+      bin/shakapacker-config --validate --verbose
       ```
 
    3. **Test individual builds manually** using the same configuration:

data/eslint.config.fast.js

@@ -25,6 +25,14 @@ module.exports = [
     ]
   },
 
+  // Global linter options
+  {
+    linterOptions: {
+      reportUnusedDisableDirectives: "error",
+      reportUnusedInlineConfigs: "error"
+    }
+  },
+
   // Base config for all JS files
   ...compat.extends("airbnb"),
   {

data/eslint.config.js

@@ -23,10 +23,20 @@ module.exports = [
       // Temporarily ignore TypeScript files until technical debt is resolved
       // See ESLINT_TECHNICAL_DEBT.md for tracking
       // TODO: Remove this once ESLint issues are fixed (tracked in #723)
-      "package/**/*.ts"
+      // Exception: configExporter is being fixed in #707
+      "package/**/*.ts",
+      "!package/configExporter/**/*.ts" // Enable linting for configExporter (issue #707)
     ]
   },
 
+  // Global linter options
+  {
+    linterOptions: {
+      reportUnusedDisableDirectives: "error",
+      reportUnusedInlineConfigs: "error"
+    }
+  },
+
   // Base config for all JS files
   ...compat.extends("airbnb"),
   {
@@ -181,21 +191,48 @@ module.exports = [
     }
   },
   {
+    // #707: Significant type safety improvements in configExporter module!
+    // - configFile.ts: ✅ Fully type-safe (0 type errors)
+    // - buildValidator.ts: ✅ Fully type-safe (0 type errors)
+    // - yamlSerializer.ts: ✅ Fully type-safe (0 type errors)
+    // - cli.ts: ⚠️ Partial (dynamic webpack config loading requires some `any`)
+    //
+    // Remaining overrides are for:
+    // 1. Code style/organization (not type safety)
+    // 2. Dynamic require() in cli.ts for webpack config loading
     files: ["package/configExporter/**/*.ts"],
+    rules: {
+      // Code organization (functions before use due to large file)
+      "@typescript-eslint/no-use-before-define": "off",
+      // Import style (CommonJS require for dynamic imports)
+      "@typescript-eslint/no-require-imports": "off",
+      "import/no-dynamic-require": "off",
+      "global-require": "off",
+      // Class methods that are part of public API
+      "class-methods-use-this": "off",
+      // Template expressions (valid use cases with union types)
+      "@typescript-eslint/restrict-template-expressions": "off",
+      // Style preferences
+      "no-continue": "off",
+      "import/prefer-default-export": "off",
+      "no-await-in-loop": "off",
+      "no-underscore-dangle": "off",
+      "no-shadow": "off",
+      "no-restricted-globals": "off",
+      "@typescript-eslint/no-unused-vars": "off",
+      "@typescript-eslint/require-await": "off"
+    }
+  },
+  {
+    // cli.ts: Dynamic webpack config loading requires `any` types
+    // This is acceptable as webpack configs can have any shape
+    files: ["package/configExporter/cli.ts"],
     rules: {
       "@typescript-eslint/no-explicit-any": "off",
       "@typescript-eslint/no-unsafe-assignment": "off",
       "@typescript-eslint/no-unsafe-member-access": "off",
       "@typescript-eslint/no-unsafe-call": "off",
-      "@typescript-eslint/no-unsafe-return": "off",
-      "@typescript-eslint/no-unsafe-argument": "off",
-      "@typescript-eslint/no-unsafe-function-type": "off",
-      "@typescript-eslint/no-unused-vars": "off",
-      "@typescript-eslint/require-await": "off",
-      "no-await-in-loop": "off",
-      "import/prefer-default-export": "off",
-      "global-require": "off",
-      "no-underscore-dangle": "off"
+      "@typescript-eslint/no-unsafe-return": "off"
     }
   },
   {

data/knip.ts

@@ -47,7 +47,14 @@ const config: KnipConfig = {
     "css-loader",
     "esbuild-loader",
     "swc-loader",
-    "webpack"
+    "webpack",
+    // eslint-config-airbnb isn't detected because it's used by compat.extends("airbnb"),
+    // the rest are its peerDependencies
+    "eslint-config-airbnb",
+    "eslint-plugin-import",
+    "eslint-plugin-jsx-a11y",
+    "eslint-plugin-react",
+    "eslint-plugin-react-hooks"
   ]
 }
 

data/lib/install/config/shakapacker.yml

@@ -67,9 +67,8 @@ default: &default
   compiler_strategy: digest
 
   # Select whether the compiler will always use a content hash and not just in production
-  # Don't use contentHash except for production for performance
-  # https://webpack.js.org/guides/build-performance/#avoid-production-specific-tooling
-  useContentHash: false
+  # Content hashes are recommended for production cache busting
+  useContentHash: true
 
   # Setting the asset host here will override Rails.application.config.asset_host.
   # Here, you can set different asset_host per environment. Note that
@@ -101,6 +100,10 @@ development:
   compile: true
   compiler_strategy: mtime
 
+  # Disable content hashes in development for faster builds
+  # https://webpack.js.org/guides/caching/
+  useContentHash: false
+
   # Early hints disabled by default in development
   # To enable: Set enabled: true AND start Puma with: bundle exec puma --early-hints
   # See docs/early_hints_new_api.md for setup instructions
@@ -164,9 +167,6 @@ production:
   # Production depends on precompilation of packs prior to booting for performance.
   compile: false
 
-  # Use content hash for naming assets. Cannot be overridden in production.
-  useContentHash: true
-
   # Cache manifest.json for performance
   cache_manifest: true