@@ -15,80 +15,96 @@ This guide covers common webpack build errors encountered when using react_on_ra
1515** Note:** This error only occurs if you're using the optional ` js-routes ` gem to access Rails routes in JavaScript.
1616
1717### Error Message
18+
1819```
1920Cannot read properties of undefined (reading 'module')
2021TypeError: Cannot read properties of undefined (reading 'module')
2122 at ProvidedDependencyTemplate.apply
2223```
2324
2425### Root Cause
26+
2527This error occurs when:
28+
26291 . Your webpack config references Rails routes via ProvidePlugin
27302 . The ` js-routes ` gem hasn't generated the JavaScript routes file
28313 . You're using ` js-routes ` integration but missing the generated file
2932
3033### When You Need js-routes
34+
3135` js-routes ` is ** optional** and typically used when:
36+
3237- Rails-heavy apps with React components that need to navigate to Rails routes
3338- Server-side rendered apps mixing Rails and React routing
3439- Legacy Rails apps migrating ERB views to React
3540- Apps using Rails routing patterns for RESTful APIs
3641
3742### When You DON'T Need js-routes
43+
3844Most modern React apps use:
45+
3946- Client-side routing (React Router) instead of Rails routes
4047- Hardcoded API endpoints or environment variables
4148- SPA (Single Page App) architecture with API-only Rails backend
4249
4350### Solution (if using js-routes)
51+
44521 . ** Generate JavaScript routes file:**
53+
4554 ``` bash
4655 bundle exec rails js:export
4756 ```
4857
49582 . ** Verify the routes file was created:**
59+
5060 ``` bash
5161 ls app/javascript/utils/routes.js
5262 ```
5363
54643 . ** Check webpack configuration includes ProvidePlugin:**
5565 ``` javascript
5666 new webpack.ProvidePlugin ({
57- Routes: " $app/utils/routes"
58- })
67+ Routes: ' $app/utils/routes' ,
68+ });
5969 ```
6070
6171### Alternative Solution (if NOT using js-routes)
72+
6273Remove the Routes ProvidePlugin from your webpack configuration:
74+
6375``` javascript
6476// Remove this line if you don't use js-routes
6577new webpack.ProvidePlugin ({
66- Routes: " $app/utils/routes" // ← Remove this
67- })
78+ Routes: ' $app/utils/routes' , // ← Remove this
79+ });
6880```
6981
7082## ProvidePlugin Module Resolution Errors
7183
7284### Common Error Patterns
85+
7386- ` Cannot read properties of undefined (reading 'module') `
7487- ` Module not found: Error: Can't resolve 'module_name' `
7588- ` ERROR in ./path/to/file.js: Cannot find name 'GlobalVariable' `
7689
7790### Debugging Steps
7891
79921 . ** Check file existence:**
93+
8094 ``` bash
8195 find app/javascript -name " routes.*" -type f
8296 find app/javascript -name " *global*" -type f
8397 ```
8498
85992 . ** Verify webpack aliases:**
100+
86101 ``` javascript
87102 // In your webpack config
88103 console .log (' Webpack aliases:' , config .resolve .alias );
89104 ```
90105
911063 . ** Test module resolution:**
107+
92108 ``` bash
93109 # Run webpack with debug output
94110 bin/shakapacker --debug-shakapacker
@@ -109,6 +125,7 @@ new webpack.ProvidePlugin({
109125## Environment Setup Dependencies
110126
111127### Rails Environment Required
128+
112129Some operations require a working Rails environment:
113130
114131- ` rails js:export ` (generates routes - ** only needed if using js-routes gem** )
@@ -118,17 +135,20 @@ Some operations require a working Rails environment:
118135### Common Issues
119136
1201371 . ** Database Connection Errors:**
138+
121139 ```
122140 MONGODB | Error checking localhost:27017: Connection refused
123141 ```
124142
125143 ** Solution:** These are usually warnings and don't prevent operation. To silence:
144+
126145 ``` bash
127146 # Run with minimal environment
128147 RAILS_ENV=development bundle exec rails js:export
129148 ```
130149
1311502 . ** Missing Dependencies:**
151+
132152 ```
133153 sidekiq-pro is not installed
134154 ```
@@ -138,6 +158,7 @@ Some operations require a working Rails environment:
138158### Workarounds
139159
1401601 . ** Skip database initialization:**
161+
141162 ``` bash
142163 DATABASE_URL=sqlite3:tmp/db.sqlite3 rails js:export
143164 ```
@@ -152,14 +173,15 @@ Some operations require a working Rails environment:
152173### Version Compatibility Matrix
153174
154175| react_on_rails | Shakapacker | Webpack | Node.js |
155- | ---------------- | ------------- | --------- | --------- |
176+ | -------------- | ----------- | ------- | ------- |
156177| v16.x | >= 6.0 | v5 | 20-22 |
157178| v14.x | >= 6.0 | v5 | 18-20 |
158179| v13.x | >= 6.0 | v5 | 16-18 |
159180
160181### Common Upgrade Issues
161182
1621831 . ** Webpacker to Shakapacker migration incomplete:**
184+
163185 ``` bash
164186 # Remove webpacker references
165187 grep -r " webpacker" config/
@@ -172,6 +194,7 @@ Some operations require a working Rails environment:
172194 ```
173195
174196### Migration Steps
197+
1751981 . Follow the [ Shakapacker upgrade guide] ( https://github.com/shakacode/shakapacker/blob/main/docs/v6_upgrade.md )
1761992 . Update webpack configurations
1772003 . Regenerate configurations with ` rails generate react_on_rails:install `
0 commit comments