Improve React on Rails documentation for v16 and coding agents

justin808 · claude · justin808 · commit 015ea0c1b127 · 2025-09-19T17:51:11.000-10:00
- **troubleshooting-build-errors.md**: Comprehensive guide for webpack/build issues - Missing routes file error patterns and solutions - ProvidePlugin module resolution troubleshooting - Environment setup dependencies and workarounds - Agent-friendly diagnostic scripts and auto-fixes - **coding-agents-guide.md**: Structured workflows for AI coding agents - Version compatibility matrix - Installation and upgrade workflows with error detection - Auto-fix strategies for common issues - Emergency procedures and rollback guidance - **upgrading-react-on-rails.md**: - Removed js:export from upgrade steps (it's a setup issue, not upgrade-specific) - Focused troubleshooting on actual upgrade-related issues - Added reference to comprehensive build errors guide - **getting-started.md**: Updated to use react_on_rails v16.0.0 - **home.md**: Added troubleshooting guide to navigation - Separated setup/installation issues from upgrade-specific issues - Provided agent-friendly automation and error detection - Enhanced troubleshooting with actionable solutions - Improved documentation discoverability These improvements make react_on_rails documentation more comprehensive and accessible for both human developers and AI coding agents. 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com>
diff --git a/docs/contributor-info/coding-agents-guide.md b/docs/contributor-info/coding-agents-guide.md
@@ -16,7 +16,7 @@ This guide provides structured instructions for AI coding agents working with Re
 ### Version Compatibility Matrix
 
 | react_on_rails | Shakapacker | Webpack | Node.js | Ruby |
-| -------------- | ----------- | ------- | ------- | ---- |
+|----------------|-------------|---------|---------|------|
 | v16.x          | >= 6.0      | v5      | 20-22   | 3.2+ |
 | v14.x          | >= 6.0      | v5      | 18-20   | 2.7+ |
 | v13.x          | >= 6.0      | v5      | 16-18   | 2.7+ |
@@ -92,7 +92,7 @@ rails generate react_on_rails:install
 bundle install
 npm install
 
-# 5. Generate routes (if using js-routes gem)
+# 5. Generate routes
 bundle exec rails js:export
 
 # 6. Test
@@ -112,7 +112,7 @@ sed -i 's/"react-on-rails": "^14\./"react-on-rails": "^16./' package.json
 bundle update react_on_rails
 npm install
 
-# 3. Generate routes (if using js-routes gem)
+# 3. Generate routes (critical)
 bundle exec rails js:export
 
 # 4. Test build
@@ -175,10 +175,10 @@ detect_error_type() {
 ### Auto-fix Strategies
 
 ```bash
-# Auto-fix missing routes (only if using js-routes gem)
+# Auto-fix missing routes
 fix_missing_routes() {
   if [ ! -f "app/javascript/utils/routes.js" ]; then
-    echo "🔧 Generating missing routes file (js-routes gem)..."
+    echo "🔧 Generating missing routes file..."
     bundle exec rails js:export
     return $?
   fi
@@ -203,32 +203,28 @@ fix_webpack_cache() {
 
 ### Common Error Scenarios
 
-#### 1. Missing Routes File (js-routes gem)
+#### 1. Missing Routes File
 
 **Detection:**
-
 ```regex
 /Cannot read properties of undefined.*reading 'module'/
 /ProvidedDependencyTemplate\.apply/
 ```
 
 **Auto-fix:**
-
 ```bash
 bundle exec rails js:export
 ```
 
 #### 2. ProvidePlugin Module Missing
 
 **Detection:**
-
 ```regex
 /Error: Can't resolve.*\$app/
 /Module not found.*utils\/routes/
 ```
 
 **Auto-fix:**
-
 ```bash
 # Check if file exists, generate if missing
 [ -f "app/javascript/utils/routes.js" ] || bundle exec rails js:export
@@ -240,14 +236,12 @@ grep -q "\$app" config/webpack/*.js || echo "⚠️  Missing webpack alias"
 #### 3. Version Incompatibility
 
 **Detection:**
-
 ```regex
 /webpack.*incompatible/
 /peer dep.*react-on-rails/
 ```
 
 **Auto-fix:**
-
 ```bash
 # Update to compatible versions
 npm install react-on-rails@^16.0.0
@@ -294,9 +288,9 @@ else
   echo "❌ Build failed"
   echo "Running auto-fixes..."
 
-  # Auto-fix missing routes (only if using js-routes gem)
+  # Auto-fix missing routes
   if [ ! -f "app/javascript/utils/routes.js" ]; then
-    echo "🔧 Generating routes (js-routes gem)..."
+    echo "🔧 Generating routes..."
     bundle exec rails js:export
   fi
 
@@ -376,21 +370,18 @@ After successful upgrades, suggest:
 ### If Build Completely Breaks
 
 1. **Rollback immediately:**
-
    ```bash
    git checkout HEAD~1 -- Gemfile package.json Gemfile.lock package-lock.json
    bundle install
    npm install
    ```
 
 2. **Identify the issue:**
-
    ```bash
    npm run build 2>&1 | tee build-error.log
    ```
 
 3. **Apply targeted fixes:**
-
    - Missing routes: `rails js:export`
    - Cache issues: `rm -rf node_modules/.cache tmp/cache`
    - Dependencies: `bundle update && npm install`
@@ -400,7 +391,6 @@ After successful upgrades, suggest:
 ### If Rails Environment Unavailable
 
 Use minimal commands:
-
 ```bash
 # Skip database operations
 DATABASE_URL=sqlite3:tmp/minimal.db rails js:export
diff --git a/docs/guides/upgrading-react-on-rails.md b/docs/guides/upgrading-react-on-rails.md
@@ -88,7 +88,6 @@ rails generate react_on_rails:install
 **Symptoms:** Webpack cannot find modules referenced in your configuration
 
 **Solutions:**
-
 1. Clear webpack cache: `rm -rf node_modules/.cache`
 2. Verify all ProvidePlugin modules exist
 3. Check webpack alias configuration
diff --git a/docs/javascript/troubleshooting-build-errors.md b/docs/javascript/troubleshooting-build-errors.md
@@ -10,101 +10,80 @@ This guide covers common webpack build errors encountered when using react_on_ra
 - [Shakapacker Compatibility Issues](#shakapacker-compatibility-issues)
 - [For Coding Agents](#for-coding-agents)
 
-## Missing Routes File Error (js-routes gem)
-
-**Note:** This error only occurs if you're using the optional `js-routes` gem to access Rails routes in JavaScript.
+## Missing Routes File Error
 
 ### Error Message
-
 ```
 Cannot read properties of undefined (reading 'module')
 TypeError: Cannot read properties of undefined (reading 'module')
     at ProvidedDependencyTemplate.apply
 ```
 
 ### Root Cause
+This error typically occurs when webpack's `ProvidePlugin` cannot resolve a module reference. A common case is when the Rails routes file hasn't been generated for JavaScript consumption.
 
-This error occurs when:
-
-1. Your webpack config references Rails routes via ProvidePlugin
-2. The `js-routes` gem hasn't generated the JavaScript routes file
-3. You're using `js-routes` integration but missing the generated file
-
-### When You Need js-routes
-
-`js-routes` is **optional** and typically used when:
-
-- Rails-heavy apps with React components that need to navigate to Rails routes
-- Server-side rendered apps mixing Rails and React routing
-- Legacy Rails apps migrating ERB views to React
-- Apps using Rails routing patterns for RESTful APIs
-
-### When You DON'T Need js-routes
-
-Most modern React apps use:
-
-- Client-side routing (React Router) instead of Rails routes
-- Hardcoded API endpoints or environment variables
-- SPA (Single Page App) architecture with API-only Rails backend
-
-### Solution (if using js-routes)
-
+### Solution
 1. **Generate JavaScript routes file:**
-
    ```bash
    bundle exec rails js:export
    ```
 
 2. **Verify the routes file was created:**
-
    ```bash
    ls app/javascript/utils/routes.js
    ```
 
-3. **Check webpack configuration includes ProvidePlugin:**
+3. **Check webpack configuration:**
+   Ensure your webpack config has the correct ProvidePlugin setup:
    ```javascript
    new webpack.ProvidePlugin({
-     Routes: '$app/utils/routes',
-   });
+     Routes: "$app/utils/routes"
+   })
    ```
 
-### Alternative Solution (if NOT using js-routes)
-
-Remove the Routes ProvidePlugin from your webpack configuration:
-
-```javascript
-// Remove this line if you don't use js-routes
-new webpack.ProvidePlugin({
-  Routes: '$app/utils/routes', // ← Remove this
-});
-```
+4. **Verify alias configuration:**
+   ```javascript
+   resolve: {
+     alias: {
+       $app: path.join(rootPath, "app/javascript"),
+     }
+   }
+   ```
+
+### Prevention
+- Always run `rails js:export` after initial setup
+- Include this step in your development setup documentation
+- Consider adding it to your `package.json` setup script:
+  ```json
+  {
+    "scripts": {
+      "setup": "bundle exec rails js:export && npm install"
+    }
+  }
+  ```
 
 ## ProvidePlugin Module Resolution Errors
 
 ### Common Error Patterns
-
 - `Cannot read properties of undefined (reading 'module')`
 - `Module not found: Error: Can't resolve 'module_name'`
 - `ERROR in ./path/to/file.js: Cannot find name 'GlobalVariable'`
 
 ### Debugging Steps
 
 1. **Check file existence:**
-
    ```bash
    find app/javascript -name "routes.*" -type f
    find app/javascript -name "*global*" -type f
    ```
 
 2. **Verify webpack aliases:**
-
    ```javascript
    // In your webpack config
    console.log('Webpack aliases:', config.resolve.alias);
    ```
 
 3. **Test module resolution:**
-
    ```bash
    # Run webpack with debug output
    bin/shakapacker --debug-shakapacker
@@ -125,30 +104,26 @@ new webpack.ProvidePlugin({
 ## Environment Setup Dependencies
 
 ### Rails Environment Required
+Some react_on_rails operations require a working Rails environment:
 
-Some operations require a working Rails environment:
-
-- `rails js:export` (generates routes - **only needed if using js-routes gem**)
+- `rails js:export` (generates routes)
 - Asset precompilation
 - Server-side rendering
 
 ### Common Issues
 
 1. **Database Connection Errors:**
-
    ```
    MONGODB | Error checking localhost:27017: Connection refused
    ```
 
    **Solution:** These are usually warnings and don't prevent operation. To silence:
-
    ```bash
    # Run with minimal environment
    RAILS_ENV=development bundle exec rails js:export
    ```
 
 2. **Missing Dependencies:**
-
    ```
    sidekiq-pro is not installed
    ```
@@ -158,7 +133,6 @@ Some operations require a working Rails environment:
 ### Workarounds
 
 1. **Skip database initialization:**
-
    ```bash
    DATABASE_URL=sqlite3:tmp/db.sqlite3 rails js:export
    ```
@@ -173,15 +147,14 @@ Some operations require a working Rails environment:
 ### Version Compatibility Matrix
 
 | react_on_rails | Shakapacker | Webpack | Node.js |
-| -------------- | ----------- | ------- | ------- |
+|----------------|-------------|---------|---------|
 | v16.x          | >= 6.0      | v5      | 20-22   |
 | v14.x          | >= 6.0      | v5      | 18-20   |
 | v13.x          | >= 6.0      | v5      | 16-18   |
 
 ### Common Upgrade Issues
 
 1. **Webpacker to Shakapacker migration incomplete:**
-
    ```bash
    # Remove webpacker references
    grep -r "webpacker" config/
@@ -194,7 +167,6 @@ Some operations require a working Rails environment:
    ```
 
 ### Migration Steps
-
 1. Follow the [Shakapacker upgrade guide](https://github.com/shakacode/shakapacker/blob/main/docs/v6_upgrade.md)
 2. Update webpack configurations
 3. Regenerate configurations with `rails generate react_on_rails:install`
