From 015ea0c1b1279a0e6efe8505c460c1d0d23b31f3 Mon Sep 17 00:00:00 2001
From: Justin Gordon <justin@shakacode.com>
Date: Wed, 17 Sep 2025 15:31:30 -1000
Subject: [PATCH 1/6] Improve React on Rails documentation for v16 and coding
 agents
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- **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>
---
 docs/contributor-info/coding-agents-guide.md  | 26 ++----
 docs/guides/upgrading-react-on-rails.md       |  1 -
 .../troubleshooting-build-errors.md           | 88 +++++++------------
 3 files changed, 38 insertions(+), 77 deletions(-)

diff --git a/docs/contributor-info/coding-agents-guide.md b/docs/contributor-info/coding-agents-guide.md
index 71c35f1266..f3c89de41b 100644
--- 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,17 +203,15 @@ 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
 ```
@@ -221,14 +219,12 @@ 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,7 +370,6 @@ 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
@@ -384,13 +377,11 @@ After successful upgrades, suggest:
    ```
 
 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
index 9e07b59ac5..00cc9eba1f 100644
--- 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
index 79dde2c12f..d9d7549fbf 100644
--- a/docs/javascript/troubleshooting-build-errors.md
+++ b/docs/javascript/troubleshooting-build-errors.md
@@ -10,12 +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 (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')
@@ -23,66 +20,51 @@ 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.
 
-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'`
@@ -90,21 +72,18 @@ new webpack.ProvidePlugin({
 ### 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,7 +147,7 @@ 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   |
@@ -181,7 +155,6 @@ Some operations require a working Rails environment:
 ### 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`

From 82b1a1a15a36fecc89928258d10e8824bbf5ab52 Mon Sep 17 00:00:00 2001
From: Justin Gordon <justin@shakacode.com>
Date: Wed, 17 Sep 2025 15:39:33 -1000
Subject: [PATCH 2/6] Clarify js-routes as optional dependency in documentation
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

## 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 <noreply@anthropic.com>
---
 docs/contributor-info/coding-agents-guide.md  | 14 ++---
 .../troubleshooting-build-errors.md           | 61 ++++++++++---------
 2 files changed, 40 insertions(+), 35 deletions(-)

diff --git a/docs/contributor-info/coding-agents-guide.md b/docs/contributor-info/coding-agents-guide.md
index f3c89de41b..406e085a70 100644
--- a/docs/contributor-info/coding-agents-guide.md
+++ b/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
 
diff --git a/docs/javascript/troubleshooting-build-errors.md b/docs/javascript/troubleshooting-build-errors.md
index d9d7549fbf..51d143cf82 100644
--- a/docs/javascript/troubleshooting-build-errors.md
+++ b/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
 

From bc9ca1033dc574e89d124ab99cd720e6167aa3fe Mon Sep 17 00:00:00 2001
From: Justin Gordon <justin@shakacode.com>
Date: Sat, 20 Sep 2025 13:56:19 -1000
Subject: [PATCH 3/6] Fix formatting issues in documentation after merge
 conflict resolution
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Apply Prettier formatting to documentation files that were left with
inconsistent formatting after resolving merge conflicts during rebase.

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

Co-Authored-By: Claude <noreply@anthropic.com>
---
 docs/contributor-info/coding-agents-guide.md  | 12 ++++++-
 docs/guides/upgrading-react-on-rails.md       |  1 +
 .../troubleshooting-build-errors.md           | 33 ++++++++++++++++---
 3 files changed, 40 insertions(+), 6 deletions(-)

diff --git a/docs/contributor-info/coding-agents-guide.md b/docs/contributor-info/coding-agents-guide.md
index 406e085a70..71c35f1266 100644
--- 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+ |
@@ -206,12 +206,14 @@ fix_webpack_cache() {
 #### 1. Missing Routes File (js-routes gem)
 
 **Detection:**
+
 ```regex
 /Cannot read properties of undefined.*reading 'module'/
 /ProvidedDependencyTemplate\.apply/
 ```
 
 **Auto-fix:**
+
 ```bash
 bundle exec rails js:export
 ```
@@ -219,12 +221,14 @@ 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
@@ -236,12 +240,14 @@ 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
@@ -370,6 +376,7 @@ 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
@@ -377,11 +384,13 @@ After successful upgrades, suggest:
    ```
 
 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`
@@ -391,6 +400,7 @@ 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
index 00cc9eba1f..9e07b59ac5 100644
--- a/docs/guides/upgrading-react-on-rails.md
+++ b/docs/guides/upgrading-react-on-rails.md
@@ -88,6 +88,7 @@ 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
index 51d143cf82..79dde2c12f 100644
--- a/docs/javascript/troubleshooting-build-errors.md
+++ b/docs/javascript/troubleshooting-build-errors.md
@@ -15,6 +15,7 @@ This guide covers common webpack build errors encountered when using react_on_ra
 **Note:** This error only occurs if you're using the optional `js-routes` gem to access Rails routes in JavaScript.
 
 ### Error Message
+
 ```
 Cannot read properties of undefined (reading 'module')
 TypeError: Cannot read properties of undefined (reading 'module')
@@ -22,31 +23,40 @@ TypeError: Cannot read properties of undefined (reading 'module')
 ```
 
 ### Root Cause
+
 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
    ```
 
 2. **Verify the routes file was created:**
+
    ```bash
    ls app/javascript/utils/routes.js
    ```
@@ -54,22 +64,25 @@ Most modern React apps use:
 3. **Check webpack configuration includes ProvidePlugin:**
    ```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
-})
+  Routes: '$app/utils/routes', // ← Remove this
+});
 ```
 
 ## 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'`
@@ -77,18 +90,21 @@ new webpack.ProvidePlugin({
 ### 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
@@ -109,6 +125,7 @@ new webpack.ProvidePlugin({
 ## Environment Setup Dependencies
 
 ### Rails Environment Required
+
 Some operations require a working Rails environment:
 
 - `rails js:export` (generates routes - **only needed if using js-routes gem**)
@@ -118,17 +135,20 @@ Some operations require a working Rails environment:
 ### 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
    ```
@@ -138,6 +158,7 @@ Some operations require a working Rails environment:
 ### Workarounds
 
 1. **Skip database initialization:**
+
    ```bash
    DATABASE_URL=sqlite3:tmp/db.sqlite3 rails js:export
    ```
@@ -152,7 +173,7 @@ 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   |
@@ -160,6 +181,7 @@ Some operations require a working Rails environment:
 ### Common Upgrade Issues
 
 1. **Webpacker to Shakapacker migration incomplete:**
+
    ```bash
    # Remove webpacker references
    grep -r "webpacker" config/
@@ -172,6 +194,7 @@ 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`

From bdda2de6f9b84b7f82b3acd54317c6cdc0598c02 Mon Sep 17 00:00:00 2001
From: Justin Gordon <justin@shakacode.com>
Date: Sat, 20 Sep 2025 14:15:16 -1000
Subject: [PATCH 4/6] Document critical formatting rules and conflict
 resolution workflow
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Add comprehensive formatting guidelines to prevent formatting wars:

- CLAUDE.md: Add Prettier as critical requirement with merge conflict workflow
- linters.md: Add dedicated Prettier section with conflict resolution steps
- coding-agents-guide.md: Add formatting requirements for AI agents

Key principle: Prettier is the SOLE authority for formatting - never manually format code, especially during merge conflict resolution.

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

Co-Authored-By: Claude <noreply@anthropic.com>
---
 CLAUDE.md                                    | 26 ++++++++++++++++
 docs/contributor-info/coding-agents-guide.md | 17 +++++++++--
 docs/contributor-info/linters.md             | 32 ++++++++++++++++++++
 3 files changed, 73 insertions(+), 2 deletions(-)

diff --git a/CLAUDE.md b/CLAUDE.md
index dd5c622141..96138df4cd 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -9,6 +9,7 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 1. **ALWAYS run `bundle exec rubocop` and fix ALL violations**
 2. **ALWAYS ensure files end with a newline character**
 3. **NEVER push without running full lint check first**
+4. **ALWAYS let Prettier handle ALL formatting - never manually format**
 
 These requirements are non-negotiable. CI will fail if not followed.
 
@@ -33,6 +34,31 @@ These requirements are non-negotiable. CI will fail if not followed.
 - **Type checking**: `yarn run type-check`
 - **⚠️ MANDATORY BEFORE GIT PUSH**: `bundle exec rubocop` and fix ALL violations + ensure trailing newlines
 
+## ⚠️ FORMATTING RULES
+
+**Prettier is the SOLE authority for formatting. NEVER manually format code.**
+
+### Standard Workflow
+1. Make code changes
+2. Run `npx prettier --write <files>` or `rake autofix`
+3. Commit changes
+
+### Merge Conflict Resolution Workflow
+**CRITICAL**: When resolving merge conflicts, follow this exact sequence:
+
+1. **Resolve logical conflicts only** - don't worry about formatting
+2. **Add resolved files**: `git add <conflicted-files>`
+3. **Let Prettier format**: `npx prettier --write <conflicted-files>`
+4. **Add formatted files**: `git add <conflicted-files>` (if Prettier made changes)
+5. **Continue rebase/merge**: `git rebase --continue` or `git commit`
+
+**❌ NEVER manually format during conflict resolution** - this causes formatting wars between tools.
+
+### Debugging Formatting Issues
+- Check current formatting: `npx prettier --check .`
+- Fix all formatting: `npx prettier --write .`
+- If CI fails on formatting, always run Prettier, never manual fixes
+
 ### Development Setup Commands
 
 - **Initial setup**: `bundle && yarn && rake shakapacker_examples:gen_all && rake node_package && rake`
diff --git a/docs/contributor-info/coding-agents-guide.md b/docs/contributor-info/coding-agents-guide.md
index 71c35f1266..5aba85d3d9 100644
--- a/docs/contributor-info/coding-agents-guide.md
+++ b/docs/contributor-info/coding-agents-guide.md
@@ -350,7 +350,20 @@ git checkout HEAD~1 -- Gemfile package.json  # Rollback versions
 - Database warnings during `rails js:export` are usually non-fatal
 - Test builds don't require database connectivity
 
-### 6. Communication with Users
+### 6. Formatting Requirements
+
+**⚠️ CRITICAL**: Always use Prettier for formatting - never manually format code.
+
+**Merge conflict resolution workflow:**
+1. Resolve logical conflicts only (ignore formatting)
+2. `git add <resolved-files>`
+3. `npx prettier --write <resolved-files>`
+4. `git add <resolved-files>` (if Prettier made changes)
+5. Continue rebase: `git rebase --continue`
+
+**Never manually format during conflict resolution** - this causes formatting wars.
+
+### 7. Communication with Users
 
 When reporting status to users:
 
@@ -361,7 +374,7 @@ echo "⚠️  Note: Some TypeScript errors may be unrelated to react_on_rails"
 echo "🔗 Next steps: Test your application with 'bin/dev'"
 ```
 
-### 7. Documentation Updates
+### 8. Documentation Updates
 
 After successful upgrades, suggest:
 
diff --git a/docs/contributor-info/linters.md b/docs/contributor-info/linters.md
index ac0f576277..d3d0a84a92 100644
--- a/docs/contributor-info/linters.md
+++ b/docs/contributor-info/linters.md
@@ -27,6 +27,38 @@ npm run lint -- --fix
 
 Autofixing is a **HUGE** time saver!
 
+## Prettier
+
+[Prettier](https://prettier.io/) handles code formatting for JavaScript, TypeScript, CSS, and Markdown files.
+
+**⚠️ CRITICAL**: Prettier is the SOLE authority for formatting. Never manually format code.
+
+### Basic Usage
+
+```bash
+# Check formatting
+npx prettier --check .
+
+# Fix formatting
+npx prettier --write .
+
+# Or use project scripts
+rake autofix
+yarn start format.listDifferent  # check only
+```
+
+### Merge Conflict Resolution
+
+When resolving merge conflicts, **NEVER manually format**. Follow this sequence:
+
+1. Resolve logical conflicts only
+2. `git add <resolved-files>`
+3. `npx prettier --write <resolved-files>`
+4. `git add <resolved-files>` (if Prettier made changes)
+5. Continue with `git rebase --continue` or `git commit`
+
+**Why this matters**: Manual formatting during conflict resolution creates "formatting wars" between tools and leads to back-and-forth formatting changes in PRs.
+
 ## ESLint
 
 See the [ESLint](https://eslint.org/) website for more information.

From 7d385a1524fe2736959c7fe2e80ac3726fc2c630 Mon Sep 17 00:00:00 2001
From: Justin Gordon <justin@shakacode.com>
Date: Sat, 20 Sep 2025 14:16:51 -1000
Subject: [PATCH 5/6] update

---
 .gitignore | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/.gitignore b/.gitignore
index e2a9a5ffdd..f0178bd96a 100644
--- a/.gitignore
+++ b/.gitignore
@@ -60,3 +60,6 @@ yalc.lock
 
 # Generated by ROR FS-based Registry
 generated
+
+# Claude Code local settings
+.claude/settings.local.json

From 34e412bddc78a6ca3a003837e3cc2e2fbf746b4c Mon Sep 17 00:00:00 2001
From: Justin Gordon <justin@shakacode.com>
Date: Sat, 20 Sep 2025 14:27:49 -1000
Subject: [PATCH 6/6] Replace manual file commands with automated rake/yarn
 scripts
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Update formatting documentation to use proper automated commands:
- Use `rake autofix` instead of manual `npx prettier --write <files>`
- Use `yarn start format.listDifferent` for checking
- Use `git add .` instead of manual file listing
- Emphasize automated workflow over manual file management

This makes the process much more reliable and less error-prone.

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

Co-Authored-By: Claude <noreply@anthropic.com>
---
 CLAUDE.md                                    | 14 +++++++-------
 docs/contributor-info/coding-agents-guide.md |  6 +++---
 docs/contributor-info/linters.md             | 17 ++++++++---------
 3 files changed, 18 insertions(+), 19 deletions(-)

diff --git a/CLAUDE.md b/CLAUDE.md
index 96138df4cd..c7543436b7 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -40,24 +40,24 @@ These requirements are non-negotiable. CI will fail if not followed.
 
 ### Standard Workflow
 1. Make code changes
-2. Run `npx prettier --write <files>` or `rake autofix`
+2. Run `rake autofix` or `yarn start format`
 3. Commit changes
 
 ### Merge Conflict Resolution Workflow
 **CRITICAL**: When resolving merge conflicts, follow this exact sequence:
 
 1. **Resolve logical conflicts only** - don't worry about formatting
-2. **Add resolved files**: `git add <conflicted-files>`
-3. **Let Prettier format**: `npx prettier --write <conflicted-files>`
-4. **Add formatted files**: `git add <conflicted-files>` (if Prettier made changes)
+2. **Add resolved files**: `git add .` (or specific files)
+3. **Auto-fix everything**: `rake autofix`
+4. **Add any formatting changes**: `git add .`
 5. **Continue rebase/merge**: `git rebase --continue` or `git commit`
 
 **❌ NEVER manually format during conflict resolution** - this causes formatting wars between tools.
 
 ### Debugging Formatting Issues
-- Check current formatting: `npx prettier --check .`
-- Fix all formatting: `npx prettier --write .`
-- If CI fails on formatting, always run Prettier, never manual fixes
+- Check current formatting: `yarn start format.listDifferent`
+- Fix all formatting: `rake autofix`
+- If CI fails on formatting, always run automated fixes, never manual fixes
 
 ### Development Setup Commands
 
diff --git a/docs/contributor-info/coding-agents-guide.md b/docs/contributor-info/coding-agents-guide.md
index 5aba85d3d9..2ca3c9f1bd 100644
--- a/docs/contributor-info/coding-agents-guide.md
+++ b/docs/contributor-info/coding-agents-guide.md
@@ -356,9 +356,9 @@ git checkout HEAD~1 -- Gemfile package.json  # Rollback versions
 
 **Merge conflict resolution workflow:**
 1. Resolve logical conflicts only (ignore formatting)
-2. `git add <resolved-files>`
-3. `npx prettier --write <resolved-files>`
-4. `git add <resolved-files>` (if Prettier made changes)
+2. `git add .` (or specific files)
+3. `rake autofix` (fixes all formatting + linting)
+4. `git add .` (if autofix made changes)
 5. Continue rebase: `git rebase --continue`
 
 **Never manually format during conflict resolution** - this causes formatting wars.
diff --git a/docs/contributor-info/linters.md b/docs/contributor-info/linters.md
index d3d0a84a92..c14b9ab392 100644
--- a/docs/contributor-info/linters.md
+++ b/docs/contributor-info/linters.md
@@ -37,14 +37,13 @@ Autofixing is a **HUGE** time saver!
 
 ```bash
 # Check formatting
-npx prettier --check .
+yarn start format.listDifferent
 
-# Fix formatting
-npx prettier --write .
-
-# Or use project scripts
+# Fix formatting (includes all linters)
 rake autofix
-yarn start format.listDifferent  # check only
+
+# Or format only
+yarn start format
 ```
 
 ### Merge Conflict Resolution
@@ -52,9 +51,9 @@ yarn start format.listDifferent  # check only
 When resolving merge conflicts, **NEVER manually format**. Follow this sequence:
 
 1. Resolve logical conflicts only
-2. `git add <resolved-files>`
-3. `npx prettier --write <resolved-files>`
-4. `git add <resolved-files>` (if Prettier made changes)
+2. `git add .` (or specific files)
+3. `rake autofix` (fixes all formatting + linting)
+4. `git add .` (if autofix made changes)
 5. Continue with `git rebase --continue` or `git commit`
 
 **Why this matters**: Manual formatting during conflict resolution creates "formatting wars" between tools and leads to back-and-forth formatting changes in PRs.