Improve Rspack Migration Documentation with Common Issues and Solutions

[justin808]

Improve Rspack Migration Documentation

Summary

The current Rspack migration documentation is missing several critical configuration details that caused build failures when migrating from webpack to Rspack. These should be added to help others avoid the same issues.

Missing Documentation Items

1. SWC React Runtime Configuration for SSR

Issue: React on Rails SSR fails with the automatic React runtime
Error: Invalid call to renderToString. Possibly you have a renderFunction...

Solution Required:

// config/swc.config.js
{
  jsc: {
    transform: {
      react: {
        runtime: 'classic',  // NOT 'automatic' for React on Rails SSR
      },
    },
  },
}

Why: The automatic runtime changes function signatures in ways that break React on Rails SSR function detection.

2. CSS Modules Configuration for SSR

Issue: Server bundle crashes with Cannot read properties of undefined (reading 'className')
Cause: CSS module exports are undefined in server-rendered code

Solution Required:

// config/rspack/serverRspackConfig.js
if (cssLoader && cssLoader.options && cssLoader.options.modules) {
  // MUST preserve existing modules config when adding exportOnlyLocals
  cssLoader.options.modules = {
    ...cssLoader.options.modules,  // Preserve namedExport, exportLocalsConvention
    exportOnlyLocals: true,
  };
}

Why: Shakapacker 9 uses namedExport: true by default. Replacing the entire modules object (instead of merging) breaks the configuration.

3. ReScript Support

Issue: ReScript compiled files fail to resolve from node_modules
Error: Module not found: Can't resolve '@glennsl/rescript-json-combinators/src/Json.bs.js'

Solution Required:

// config/rspack/commonRspackConfig.js
{
  resolve: {
    extensions: ['.css', '.ts', '.tsx', '.bs.js'],  // Add .bs.js for ReScript
  },
}

Why: Rspack doesn't automatically resolve .bs.js extensions like webpack does.

4. Build Verification Steps

The docs should include these verification steps after migration:

# 1. Clean build to catch issues early
rm -rf public/packs ssr-generated

# 2. Build and check for errors (not just warnings)
bin/shakapacker

# 3. Look for these specific error patterns:
# - "Module not found" errors (resolve issues)
# - "Cannot read properties of undefined" (CSS modules)  
# - SSR-related errors in test output

# 4. Run full test suite
bundle exec rspec

Suggested Documentation Improvements

1. Add a "Common Migration Issues" section to the Rspack migration guide with the above solutions

2. Add a checklist for React on Rails + SSR users:

   • Configure SWC for classic React runtime
   • Preserve CSS modules config in server bundle
   • Add .bs.js to resolve extensions (if using ReScript)
   • Test SSR specifically

3. Add warnings about configuration differences:

   • Rspack handles CSS modules configuration more strictly
   • SWC transpiler settings affect SSR differently than Babel
   • Module resolution may need explicit extensions

Impact

Without these docs, developers migrating to Rspack will encounter:

• Silent SSR failures that only surface in tests
• Hard-to-debug CSS module issues
• Module resolution problems with non-standard extensions

References

• Shakapacker 9.1.0
• React on Rails 16.1.1
• Migration PR: Update to Shakapacker 9.1.0 and migrate to Rspack react-webpack-rails-tutorial#680