Clarify js-routes as optional dependency in documentation

## Problem
Documentation gave the impression that js-routes was a core react_on_rails
requirement, when it's actually an optional integration used only in specific
scenarios.

## Changes Made

### troubleshooting-build-errors.md
- Added clear note that missing routes error only occurs with js-routes gem
- Explained when js-routes IS and ISN'T needed
- Provided alternative solution: remove ProvidePlugin if not using js-routes
- Distinguished modern SPA patterns from Rails-heavy integration patterns

### coding-agents-guide.md
- Added "(if using js-routes gem)" qualifier to all js:export commands
- Updated auto-fix functions to clarify js-routes context
- Modified diagnostic scripts to indicate js-routes dependency

### Environment dependencies
- Clarified that rails js:export is only needed for js-routes gem

## Result
- Documentation now accurately reflects js-routes as optional
- Developers won't be confused into thinking it's required for react_on_rails
- Clear guidance on when to use js-routes vs modern alternatives
- Better separation of concerns between react_on_rails core and optional integrations

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <[email protected]>

Author: justin808

docs/contributor-info/coding-agents-guide.md

@@ -92,7 +92,7 @@ rails generate react_on_rails:install
 bundle install
 npm install
 
-# 5. Generate routes
+# 5. Generate routes (if using js-routes gem)
 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 (critical)
+# 3. Generate routes (if using js-routes gem)
 bundle exec rails js:export
 
 # 4. Test build
@@ -175,10 +175,10 @@ detect_error_type() {
 ### Auto-fix Strategies
 
 ```bash
-# Auto-fix missing routes
+# Auto-fix missing routes (only if using js-routes gem)
 fix_missing_routes() {
   if [ ! -f "app/javascript/utils/routes.js" ]; then
-    echo "🔧 Generating missing routes file..."
+    echo "🔧 Generating missing routes file (js-routes gem)..."
     bundle exec rails js:export
     return $?
   fi
@@ -203,7 +203,7 @@ fix_webpack_cache() {
 
 ### Common Error Scenarios
 
-#### 1. Missing Routes File
+#### 1. Missing Routes File (js-routes gem)
 
 **Detection:**
 ```regex
@@ -288,9 +288,9 @@ else
   echo "❌ Build failed"
   echo "Running auto-fixes..."
 
-  # Auto-fix missing routes
+  # Auto-fix missing routes (only if using js-routes gem)
   if [ ! -f "app/javascript/utils/routes.js" ]; then
-    echo "🔧 Generating routes..."
+    echo "🔧 Generating routes (js-routes gem)..."
     bundle exec rails js:export
   fi
 

docs/javascript/troubleshooting-build-errors.md

@@ -10,7 +10,9 @@ 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
+## 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.
 
 ### Error Message
 ```
@@ -20,9 +22,25 @@ TypeError: Cannot read properties of undefined (reading 'module')
 ```
 
 ### 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.
-
-### Solution
+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)
 1. **Generate JavaScript routes file:**
    ```bash
    bundle exec rails js:export
@@ -33,34 +51,21 @@ This error typically occurs when webpack's `ProvidePlugin` cannot resolve a modu
    ls app/javascript/utils/routes.js
    ```
 
-3. **Check webpack configuration:**
-   Ensure your webpack config has the correct ProvidePlugin setup:
+3. **Check webpack configuration includes ProvidePlugin:**
    ```javascript
    new webpack.ProvidePlugin({
      Routes: "$app/utils/routes"
    })
    ```
 
-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"
-    }
-  }
-  ```
+### 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
+})
+```
 
 ## ProvidePlugin Module Resolution Errors
 
@@ -104,9 +109,9 @@ This error typically occurs when webpack's `ProvidePlugin` cannot resolve a modu
 ## 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)
+- `rails js:export` (generates routes - **only needed if using js-routes gem**)
 - Asset precompilation
 - Server-side rendering