Add Rspack migration guide for Shakapacker 9 #2131
Conversation
Closes #1863 Comprehensive guide documenting all challenges and solutions for migrating from Webpack to Rspack with Shakapacker 9: - CSS Modules breaking change (namedExport default) - Server bundle CSS extraction filter for Rspack - CSS Modules configuration preservation for SSR - Bundler auto-detection pattern for dual support - SWC React runtime considerations - ReScript module resolution Based on real-world migration experience from react-webpack-rails-tutorial. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <[email protected]>
|
Warning Rate limit exceeded@justin808 has exceeded the limit for the number of commits or files that can be reviewed per hour. Please wait 14 minutes and 27 seconds before requesting another review. ⌛ How to resolve this issue?After the wait time has elapsed, a review can be triggered using the We recommend that you space out your commits to avoid hitting the rate limit. 🚦 How do rate limits work?CodeRabbit enforces hourly rate limits for each developer per organization. Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout. Please see our FAQ for further information. 📒 Files selected for processing (1)
WalkthroughThis PR adds documentation for migrating from Webpack to Rspack with Shakapacker 9. It includes a reference link in the main README and a comprehensive migration guide covering configuration updates, CSS modules handling, SSR considerations, ReScript-specific fixes, and troubleshooting steps. Changes
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~20 minutes
Possibly related PRs
Suggested labels
Suggested reviewers
Poem
Pre-merge checks and finishing touches✅ Passed checks (5 passed)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
Code Review: Rspack Migration Guide✅ Overall AssessmentThis is excellent documentation that provides real-world migration guidance based on actual experience. The guide is well-structured, comprehensive, and addresses critical edge cases that developers will encounter. 📝 Issues Found1. CRITICAL: Package Manager InconsistencyThe guide uses Lines affected:
Fix required: # Change from:
yarn add -D @rspack/core
# To:
pnpm add -D @rspack/corePer CLAUDE.md: "Only use pnpm as the JS package manager, never npm or yarn" 2. Code Error: Undefined Variable ReferenceLine 83: References return merge({}, baseWebpackConfig, commonOptions); // commonOptions is undefined\!Fix: Either:
3. Minor: Inconsistent Code Example CompletenessLines 61-87: The first Suggestion: Add a comment indicating this is a partial example: // Partial example - see 'Complete Configuration Example' section for full context
const commonWebpackConfig = () => {
// ...🎯 Positive Highlights
💡 Suggestions for Enhancement (Optional)
✏️ Required Changes SummaryMust fix before merge:
Nice to have: 🔒 Security, Performance, Test Coverage
Great work on documenting this migration path! This will save developers significant troubleshooting time. 🎉 |
Code Review - Rspack Migration GuideThis is an excellent documentation addition that will save developers significant time when migrating to Rspack. The guide is comprehensive, well-structured, and based on real-world experience. Here's my detailed review: ✅ Strengths1. Outstanding Documentation Quality
2. Critical Breaking Changes HighlightedThe guide prominently documents the Shakapacker 9 CSS Modules breaking change ( 3. Complete Configuration Examples
4. Comprehensive CoverageAddresses all known issues from the migration:
5. Excellent Structure
📝 Suggestions for Improvement1. Minor: Package Manager ConsistencyThe guide uses Suggested changes: - yarn add -D @rspack/core
+ pnpm add -D @rspack/core
- yarn add -D patch-package postinstall-postinstall
+ pnpm add -D patch-package postinstall-postinstallImpact: Low (users will likely use their project's package manager), but consistency with project standards is good. 2. Minor: Trailing Newline CheckPer CLAUDE.md requirements:
Verification needed: # Check if file ends with newline
tail -c 1 docs/migrating/migrating-to-rspack.md | od -An -tx1Expected: Should show 3. Optional: Add Version Compatibility NoteConsider adding a compatibility matrix upfront: ## Compatibility Matrix
| Package | Minimum Version | Recommended |
|---------|----------------|-------------|
| Shakapacker | 9.0.0 | 9.3.0+ |
| @rspack/core | 1.0.0 | Latest stable |
| Node.js | 18.x | 22.x |
| React on Rails | 13.0.0 | Latest |Rationale: Helps users quickly determine if their project is ready for migration. 4. Optional: Add CHANGELOG EntryPer CLAUDE.md:
Suggested entry for CHANGELOG.md: #### Documentation
- [PR 2131](https://github.com/shakacode/react_on_rails/pull/2131) by [justin808](https://github.com/justin808) Add comprehensive Rspack migration guide for Shakapacker 9, covering CSS Modules breaking changes, SSR configuration, and bundler auto-detection patterns.Impact: Medium - this is a significant documentation addition that helps users, so it deserves a CHANGELOG mention. 🔒 Security Review✅ No security concerns identified
🧪 Testing Review✅ Test plan is appropriate
Note: markdown-link-check CI passed successfully. 🎯 Performance Considerations✅ Performance benefits clearly documented
📊 Overall AssessmentRating: Excellent (9.5/10) This documentation will likely prevent hours of debugging for users migrating to Rspack. The guide is thorough, accurate, and based on real-world experience. The minor suggestions above are mostly about consistency with project conventions rather than correctness issues. Recommended Actions:
🙏 AcknowledgmentExcellent work documenting this migration path! This will be an invaluable resource for the community. The level of detail and real-world troubleshooting guidance demonstrates deep understanding of both the tools and the pain points users face. Closes #1863 ✅ Review conducted following React on Rails CLAUDE.md guidelines |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 1
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (2)
docs/README.md(1 hunks)docs/migrating/migrating-to-rspack.md(1 hunks)
🧰 Additional context used
📓 Path-based instructions (1)
**/*
📄 CodeRabbit inference engine (CLAUDE.md)
ALWAYS ensure files end with a newline character before committing/pushing
Files:
docs/migrating/migrating-to-rspack.mddocs/README.md
🧠 Learnings (7)
📓 Common learnings
Learnt from: CR
Repo: shakacode/react_on_rails PR: 0
File: CLAUDE.md:0-0
Timestamp: 2025-11-25T08:05:17.804Z
Learning: Applies to /CHANGELOG.md : Update `/CHANGELOG.md` for user-visible changes (features, bug fixes, breaking changes, deprecations, performance improvements) to the open-source React on Rails gem and npm package
Learnt from: CR
Repo: shakacode/react_on_rails PR: 0
File: CLAUDE.md:0-0
Timestamp: 2025-11-25T08:05:17.804Z
Learning: Applies to /CHANGELOG*.md : Use changelog format: `[PR 1818](https://github.com/shakacode/react_on_rails/pull/1818) by [username](https://github.com/username)` (no hash in PR number)
📚 Learning: 2025-11-25T08:05:17.804Z
Learnt from: CR
Repo: shakacode/react_on_rails PR: 0
File: CLAUDE.md:0-0
Timestamp: 2025-11-25T08:05:17.804Z
Learning: Applies to /CHANGELOG.md : Update `/CHANGELOG.md` for user-visible changes (features, bug fixes, breaking changes, deprecations, performance improvements) to the open-source React on Rails gem and npm package
Applied to files:
docs/migrating/migrating-to-rspack.mddocs/README.md
📚 Learning: 2025-09-16T08:01:11.146Z
Learnt from: justin808
Repo: shakacode/react_on_rails PR: 1770
File: lib/generators/react_on_rails/templates/base/base/app/javascript/src/HelloWorld/ror_components/HelloWorld.client.jsx:2-2
Timestamp: 2025-09-16T08:01:11.146Z
Learning: React on Rails uses webpack CSS Modules configuration with namedExports: true, which requires the import syntax `import * as style from './file.module.css'` rather than the default export pattern. This configuration enables better tree shaking and bundle size optimization for CSS modules.
Applied to files:
docs/migrating/migrating-to-rspack.mddocs/README.md
📚 Learning: 2025-04-26T21:55:55.874Z
Learnt from: alexeyr-ci2
Repo: shakacode/react_on_rails PR: 1732
File: spec/dummy/client/app-react16/startup/ReduxSharedStoreApp.client.jsx:40-44
Timestamp: 2025-04-26T21:55:55.874Z
Learning: In the react_on_rails project, files under `app-react16` directories are copied/moved to corresponding `/app` directories during the conversion process (removing the `-react16` suffix), which affects their relative import paths at runtime.
Applied to files:
docs/migrating/migrating-to-rspack.mddocs/README.md
📚 Learning: 2025-11-25T08:05:17.804Z
Learnt from: CR
Repo: shakacode/react_on_rails PR: 0
File: CLAUDE.md:0-0
Timestamp: 2025-11-25T08:05:17.804Z
Learning: Applies to lib/react_on_rails/*.rb : Create RBS signature files for new Ruby files in `lib/react_on_rails/` by adding corresponding `.rbs` file in `sig/react_on_rails/`, adding to Steepfile, and validating before committing
Applied to files:
docs/migrating/migrating-to-rspack.md
📚 Learning: 2025-02-18T13:08:01.477Z
Learnt from: AbanoubGhadban
Repo: shakacode/react_on_rails PR: 1644
File: lib/react_on_rails/helper.rb:190-197
Timestamp: 2025-02-18T13:08:01.477Z
Learning: RSC support validation in React on Rails Pro is handled through a chain of validations:
1. Pro version check in `run_stream_inside_fiber`
2. RSC support check during pack generation via `ReactOnRailsPro.configuration.enable_rsc_support`
3. RSC support validation during component registration
This makes additional validation in the helper methods unnecessary.
Applied to files:
docs/migrating/migrating-to-rspack.mddocs/README.md
📚 Learning: 2025-11-25T08:05:17.804Z
Learnt from: CR
Repo: shakacode/react_on_rails PR: 0
File: CLAUDE.md:0-0
Timestamp: 2025-11-25T08:05:17.804Z
Learning: The `react_on_rails_pro/` directory has its own Prettier/ESLint configuration and must be linted separately
Applied to files:
docs/README.md
🪛 markdownlint-cli2 (0.18.1)
docs/migrating/migrating-to-rspack.md
201-201: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
🔇 Additional comments (2)
docs/migrating/migrating-to-rspack.md (1)
377-380: Ensure file ends with newline.Per coding guidelines, files must end with a newline character. The file currently ends at line 380 without a trailing newline.
docs/README.md (1)
30-30: LGTM!The new migration guide link is well-placed within the "Migrating from Other Solutions" section and follows the existing formatting conventions. The description clearly indicates the purpose of the guide.
Shakapacker 9.3.1+ supports css_modules_export_mode in shakapacker.yml, which is simpler than manual webpack configuration. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <[email protected]>
Summary
Closes #1863
Details
The guide covers all known issues from the migration experience:
namedExportdefault change in Shakapacker 9Test plan
🤖 Generated with Claude Code
Summary by CodeRabbit
✏️ Tip: You can customize this high-level summary in your review settings.