Fix CSS module handling in pack generator (#1769)

Enhance pack generation workflow with CSS module filtering and automated dev tooling

Major improvements to the React on Rails development experience:

  **CSS Module Fix (Fixes #1768)**
  - Add COMPONENT_EXTENSIONS regex to filter valid React component files
  - Prevent CSS modules from being processed as components, fixing build failures
  - Add comprehensive tests for file filtering logic

  **Automated Development Workflow**
  - Integrate automatic pack generation into bin/dev scripts
  - Add detailed cleaning feedback with file listing and timing
  - Unify bin/dev script to support both server and static modes
  - Replace bin/dev-static with unified approach

  **Developer Experience Improvements**
  - Enhanced rake task output with Rainbow colors and progress feedback
  - Targeted cleaning to preserve generated files while removing obsolete ones
  - Clear error messages and fail-fast behavior for pack generation
  - Add CODING_AGENTS.md guide for AI contributors

  **Technical Enhancements**
  - Refactor complex methods to meet RuboCop compliance
  - Improve error handling and edge case management
  - Update all documentation to reflect unified bin/dev approach
  - Add comprehensive test coverage for new functionality

  This change eliminates manual pack generation steps, prevents CSS module
  build failures, and significantly improves the developer onboarding
  experience while maintaining backward compatibility.

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

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

Author: justin808

CHANGELOG.md

@@ -442,7 +442,6 @@ for details.
 - Removal of config.symlink_non_digested_assets_regex as it's no longer needed with rails/webpacker.
   If any business needs this, we can move the code to a separate gem.
 - Added configuration option `same_bundle_for_client_and_server` with default `false` because
-
   1. Production applications would typically have a server bundle that differs from the client bundle
   2. This change only affects trying to use HMR with react_on_rails with rails/webpacker.
 
@@ -1160,13 +1159,11 @@ No changes.
 - Added automatic compilation of assets at precompile is now done by ReactOnRails. Thus, you don't need to provide your own `assets.rake` file that does the precompilation.
   [#398](https://github.com/shakacode/react_on_rails/pull/398) by [robwise](https://github.com/robwise), [jbhatab](https://github.com/jbhatab), and [justin808](https://github.com/justin808).
 - **Migration to v6**
-
   - Do not run the generator again if you've already run it.
 
   - See [shakacode/react-webpack-rails-tutorial/pull/287](https://github.com/shakacode/react-webpack-rails-tutorial/pull/287) for an example of upgrading from v5.
 
   - To configure the asset compilation you can either
-
     1. Specify a `config/react_on_rails` setting for `build_production_command` to be nil to turn this feature off.
     2. Specify the script command you want to run to build your production assets, and remove your `assets.rake` file.
 

CODING_AGENTS.md

@@ -0,0 +1,309 @@
+# 🤖 Coding Agents & AI Contributors Guide
+
+This guide provides specific guidelines for AI coding agents (like Claude Code) contributing to React on Rails. It supplements the main [CONTRIBUTING.md](./CONTRIBUTING.md) with AI-specific workflows and patterns.
+
+## Quick Reference Commands
+
+### Essential Commands
+
+```bash
+# Install dependencies
+bundle && yarn
+
+# Run tests
+bundle exec rspec                    # All tests (from project root)
+cd spec/dummy && bundle exec rspec   # Dummy app tests only
+
+# Linting & Formatting
+bundle exec rubocop                  # Ruby linting
+bundle exec rubocop [file_path]     # Lint specific file
+# Note: yarn format requires local setup, format manually
+
+# Development
+cd spec/dummy && foreman start       # Start dummy app with webpack
+```
+
+### CI Compliance Checklist
+
+- [ ] `bundle exec rubocop` passes with no offenses
+- [ ] All RSpec tests pass
+- [ ] No trailing whitespace
+- [ ] Line length ≤120 characters
+- [ ] Security violations properly scoped with disable comments
+
+## Development Patterns for AI Contributors
+
+### 1. Task Management
+
+Always use TodoWrite tool for multi-step tasks to:
+
+- Track progress transparently
+- Show the user what's being worked on
+- Ensure no steps are forgotten
+- Mark tasks complete as you finish them
+
+```markdown
+Example workflow:
+
+1. Analyze the problem
+2. Create test cases
+3. Implement the fix
+4. Run tests
+5. Fix linting issues
+6. Update documentation
+```
+
+### 2. Test-Driven Development
+
+When fixing bugs or adding features:
+
+1. **Create failing tests first** that reproduce the issue
+2. **Implement the minimal fix** to make tests pass
+3. **Add comprehensive test coverage** for edge cases
+4. **Verify all existing tests still pass**
+
+### 3. File Processing Guidelines
+
+When working with file generation or processing:
+
+- **Filter by extension**: Only process relevant files (e.g., `.js/.jsx/.ts/.tsx` for React components)
+- **Validate assumptions**: Don't assume all files in a directory are components
+- **Handle edge cases**: CSS modules, config files, etc. should be excluded appropriately
+
+Example from CSS module fix:
+
+```ruby
+COMPONENT_EXTENSIONS = /\.(jsx?|tsx?)$/
+
+def filter_component_files(paths)
+  paths.grep(COMPONENT_EXTENSIONS)
+end
+```
+
+## RuboCop Compliance Patterns
+
+### Common Fixes
+
+1. **Trailing Whitespace**
+
+   ```ruby
+   # Bad
+   let(:value) { "test" }
+
+   # Good
+   let(:value) { "test" }
+   ```
+
+2. **Line Length (120 chars max)**
+
+   ```ruby
+   # Bad
+   expect { eval(pack_content.gsub(/import.*from.*['"];/, "").gsub(/ReactOnRails\.register.*/, "")) }.not_to raise_error
+
+   # Good
+   sanitized_content = pack_content.gsub(/import.*from.*['"];/, "")
+                                   .gsub(/ReactOnRails\.register.*/, "")
+   expect { eval(sanitized_content) }.not_to raise_error
+   ```
+
+3. **Named Subjects (RSpec)**
+
+   ```ruby
+   # Bad
+   describe "#method_name" do
+     subject { instance.method_name(arg) }
+
+     it "does something" do
+       expect(subject).to eq "result"
+     end
+   end
+
+   # Good
+   describe "#method_name" do
+     subject(:method_result) { instance.method_name(arg) }
+
+     it "does something" do
+       expect(method_result).to eq "result"
+     end
+   end
+   ```
+
+4. **Security/Eval Violations**
+
+   ```ruby
+   # Bad
+   expect { eval(dangerous_code) }.not_to raise_error
+
+   # Good
+   # rubocop:disable Security/Eval
+   sanitized_content = dangerous_code.gsub(/harmful_pattern/, "")
+   expect { eval(sanitized_content) }.not_to raise_error
+   # rubocop:enable Security/Eval
+   ```
+
+### RuboCop Workflow
+
+1. Run `bundle exec rubocop [file]` to see violations
+2. Fix violations manually or with auto-correct where safe
+3. Re-run to verify fixes
+4. Use disable comments sparingly and with good reason
+
+## Testing Best Practices
+
+### Test Structure
+
+```ruby
+describe "FeatureName" do
+  context "when condition A" do
+    let(:setup) { create_test_condition }
+
+    before do
+      # Setup code
+    end
+
+    it "does expected behavior" do
+      # Arrange, Act, Assert
+    end
+  end
+end
+```
+
+### Test Fixtures
+
+- Create realistic test data that represents edge cases
+- Use descriptive names for fixtures and variables
+- Clean up after tests (handled by RSpec automatically in most cases)
+
+### CSS Module Testing Example
+
+```ruby
+# Create test fixtures
+Write.create("ComponentWithCSSModule.module.css", css_content)
+Write.create("ComponentWithCSSModule.jsx", jsx_content)
+
+# Test the behavior
+it "ignores CSS module files during pack generation" do
+  generated_packs = PacksGenerator.instance.generate_packs_if_stale
+  expect(generated_packs).not_to include("ComponentWithCSSModule.module.js")
+end
+```
+
+## Git & PR Workflow
+
+### Branch Management
+
+```bash
+git checkout -b fix/descriptive-name
+# Make changes
+git add .
+git commit -m "Descriptive commit message
+
+- Bullet points for major changes
+- Reference issue numbers
+- Include 🤖 Generated with Claude Code signature"
+
+git push -u origin fix/descriptive-name
+```
+
+### Commit Message Format
+
+```
+Brief description of the change
+
+- Detailed bullet points of what changed
+- Why the change was needed
+- Any breaking changes or considerations
+
+Fixes #issue_number
+
+🤖 Generated with [Claude Code](https://claude.ai/code)
+
+Co-Authored-By: Claude <[email protected]>
+```
+
+### PR Creation
+
+Use `gh pr create` with:
+
+- Clear title referencing the issue
+- Comprehensive description with summary and test plan
+- Link to the issue being fixed
+- Include the Claude Code signature
+
+## Common Pitfalls & Solutions
+
+### 1. File Path Issues
+
+- Always use absolute paths in tools
+- Check current working directory with `pwd`
+- Use proper path joining methods
+
+### 2. Test Environment
+
+- Run tests from correct directory (often project root)
+- Understand the difference between gem tests vs dummy app tests
+- Clean up test artifacts appropriately
+
+### 3. Dependency Management
+
+- Don't assume packages are installed globally
+- Use `bundle exec` for Ruby commands
+- Verify setup with `bundle && yarn` when needed
+
+### 4. RuboCop Configuration
+
+- Different rules may apply to different directories
+- Use `bundle exec rubocop` (not global rubocop)
+- Check `.rubocop.yml` files for project-specific rules
+
+## Debugging Workflow
+
+1. **Understand the Problem**
+   - Read the issue carefully
+   - Reproduce the bug if possible
+   - Identify root cause
+
+2. **Create Minimal Test Case**
+   - Write failing test that demonstrates issue
+   - Keep it focused and minimal
+
+3. **Implement Fix**
+   - Make smallest change possible
+   - Ensure fix doesn't break existing functionality
+   - Follow existing code patterns
+
+4. **Verify Solution**
+   - All new tests pass
+   - All existing tests still pass
+   - RuboCop compliance maintained
+   - Manual testing if applicable
+
+## IDE Configuration for AI Context
+
+When analyzing codebases, ignore these directories to avoid confusion:
+
+- `/coverage`, `/tmp`, `/gen-examples`
+- `/node_package/lib`, `/node_modules`
+- `/spec/dummy/app/assets/webpack`
+- `/spec/dummy/log`, `/spec/dummy/node_modules`, `/spec/dummy/tmp`
+- `/spec/react_on_rails/dummy-for-generators`
+
+## Communication with Human Maintainers
+
+- Be transparent about AI-generated changes
+- Explain reasoning behind implementation choices
+- Ask for clarification when requirements are ambiguous
+- Provide comprehensive commit messages and PR descriptions
+- Include test plans and verification steps
+
+## Resources
+
+- [Main Contributing Guide](./CONTRIBUTING.md)
+- [Pull Request Guidelines](./docs/contributor-info/pull-requests.md)
+- [Generator Testing](./docs/contributor-info/generator-testing.md)
+- [RuboCop Documentation](https://docs.rubocop.org/)
+- [RSpec Best Practices](https://rspec.info/)
+
+---
+
+This guide evolves based on AI contributor experiences. Suggest improvements via issues or PRs!

docs/additional-details/migrating-from-react-rails.md

@@ -3,19 +3,16 @@
 In this guide, it is assumed that you have upgraded the `react-rails` project to use `shakapacker` version 7. To this end, check out [Shakapacker v7 upgrade guide](https://github.com/shakacode/shakapacker/tree/master/docs/v7_upgrade.md). Upgrading `react-rails` to version 3 can make the migration smoother but it is not required.
 
 1. Update Deps
-
    1. Replace `react-rails` in `Gemfile` with the latest version of `react_on_rails` and run `bundle install`.
    2. Remove `react_ujs` from `package.json` and run `yarn install`.
    3. Commit changes!
 
 2. Run `rails g react_on_rails:install` but do not commit the change. `react_on_rails` installs node dependencies and also creates sample React component, Rails view/controller, and updates `config/routes.rb`.
 
 3. Adapt the project: Check the changes and carefully accept, reject, or modify them as per your project's needs. Besides changes in `config/shakapacker` or `babel.config` which are project-specific, here are the most noticeable changes to address:
-
    1. Check Webpack config files at `config/webpack/*`. If coming from `react-rails` v3, the changes are minor since you have already made separate configurations for client and server bundles. The most important change here is to notice the different names for the server bundle entry file. You may choose to stick with `server_rendering.js` or use `server-bundle.js` which is the default name in `react_on_rails`. The decision made here affects the other steps.
 
    2. In `app/javascript` directory you may notice some changes.
-
       1. `react_on_rails` by default uses `bundles` directory for the React components. You may choose to rename `components` into `bundles` to follow the convention.
 
       2. `react_on_rails` uses `client-bundle.js` and `server-bundle.js` instead of `application.js` and `server_rendering.js`. There is nothing special about these names. It can be set to use any other name (as mentioned above). If you too choose to follow the new names, consider updating the relevant `javascript_pack_tag` in your Rails views.

docs/getting-started.md

@@ -38,9 +38,8 @@ You may need to check [the instructions for installing into an existing Rails ap
    ```
 
 3. Start the app:
-
    - Run `./bin/dev` for HMR
-   - Run `./bin/dev-static` for statically created bundles (no HMR)
+   - Run `./bin/dev static` for statically created bundles (no HMR)
 
 4. Visit http://localhost:3000/hello_world.
 

docs/guides/streaming-server-rendering.md

@@ -119,7 +119,6 @@ You can test your application by running `rails server` and navigating to the ap
 When a user visits the page, they'll experience the following sequence:
 
 1. The initial HTML shell is sent immediately, including:
-
    - The page layout
    - Any static content (like the `<h1>` and footer)
    - Placeholder content for the React component (typically a loading state)
@@ -165,13 +164,11 @@ Streaming SSR is particularly valuable in specific scenarios. Here's when to con
 ### Ideal Use Cases
 
 1. **Data-Heavy Pages**
-
    - Pages that fetch data from multiple sources
    - Dashboard-style layouts where different sections can load independently
    - Content that requires heavy processing or computation
 
 2. **Progressive Enhancement**
-
    - When you want users to see and interact with parts of the page while others load
    - For improving perceived performance on slower connections
    - When different parts of your page have different priority levels

docs/guides/tutorial.md

@@ -134,7 +134,7 @@ Then run the server with one of the following options:
 ```bash
 ./bin/dev # For HMR
 # or
-./bin/dev-static # Without HMR, statically creating the bundles
+./bin/dev static # Without HMR, statically creating the bundles
 ```
 
 Visit [http://localhost:3000/hello_world](http://localhost:3000/hello_world) and see your **React On Rails** app running!