Add rake task to generate and export reference webpack/rspack configurations

[justin808]

Summary

Create a contributor rake task that generates fresh webpack AND rspack configuration exports for documentation purposes. These exported configs can serve as canonical reference examples for users and AI analysis.

Task Description

Add a rake task (e.g., rake docs:export_configs) that:

1. Generates a fresh Rails + React on Rails app in a gitignored directory (e.g., tmp/config-export-app/)
2. Runs the generators for both webpack and rspack:
   • rails new with appropriate flags
   • rails generate react_on_rails:install (webpack version)
   • Generates the standard 4-file webpack configuration setup
   • Exports webpack configs using bin/export-bundler-config --doctor
   • Exports webpack dev server config (with HMR) by running bin/shakapacker-dev-server and capturing config
   • Repeats for rspack configuration
3. Exports configurations for both bundlers:
   • Runs bin/export-bundler-config --doctor for webpack setup (4 files)
   • Exports webpack dev client config WITH HMR enabled (captures dev server configuration)
   • Runs bin/export-bundler-config --doctor for rspack setup (4 files)
   • Exports rspack dev client config WITH HMR enabled (captures dev server configuration)
4. Moves exported files to organized docs directory (e.g., docs/reference-configs/)
5. Cleans up the temporary app directory

Expected Output

After running the task, we should have in docs/reference-configs/:

Webpack configurations (5 files):

• webpack/webpack-development-client.yaml (standard build)
• webpack/webpack-development-client-hmr.yaml (dev server with HMR)
• webpack/webpack-development-server.yaml
• webpack/webpack-production-client.yaml
• webpack/webpack-production-server.yaml

Rspack configurations (5 files):

• rspack/rspack-development-client.yaml (standard build)
• rspack/rspack-development-client-hmr.yaml (dev server with HMR)
• rspack/rspack-development-server.yaml
• rspack/rspack-production-client.yaml
• rspack/rspack-production-server.yaml

Total: 10 YAML configuration files

The HMR configs are important because they show:

• Dev server configuration (port, host, HTTPS, etc.)
• Hot Module Replacement settings
• Live reload configuration
• Proxy settings
• Different plugin configurations vs standard builds

Benefits

1. Always up-to-date references: Contributors can regenerate these after changes to default configurations
2. Documentation: Users can reference these canonical examples for both bundlers
3. AI Analysis: The Shakapacker AI prompt can link directly to these stable reference files
4. Testing: Ensures our default generators produce valid, exportable configurations for both bundlers
5. Migration Support: Users migrating between webpack ↔ rspack can compare configurations
6. Dev Server Troubleshooting: HMR configs help debug dev server and hot reload issues

Implementation Notes

• Directory structure:

  tmp/
    config-export-app/     # Gitignored, temporary Rails app
  docs/
    reference-configs/
      webpack/
        webpack-development-client.yaml
        webpack-development-client-hmr.yaml
        webpack-development-server.yaml
        webpack-production-client.yaml
        webpack-production-server.yaml
      rspack/
        rspack-development-client.yaml
        rspack-development-client-hmr.yaml
        rspack-development-server.yaml
        rspack-production-client.yaml
        rspack-production-server.yaml
  

• Add to .gitignore:

  tmp/config-export-app/
  

• Keep the exported YAMLs in git for easy reference

• For HMR configs, may need to:

  • Temporarily start dev server
  • Export config while server is configured for HMR
  • Or use environment variable to force dev server mode during export

• Consider creating two separate temporary apps or switching bundler config between exports

Related

This supports the Shakapacker PR #695 which generates AI analysis prompts. Once these reference configs exist in the React on Rails repo, the AI prompt can link to them directly.

Acceptance Criteria

• Rake task exists and runs successfully
• Task generates clean Rails + React on Rails app
• Exported configs for BOTH webpack and rspack are generated (10 files total)
• HMR configs captured for both bundlers showing dev server configuration
• Files are organized in docs/reference-configs/webpack/ and docs/reference-configs/rspack/
• Temporary app directory is cleaned up after export
• .gitignore updated to exclude temporary directory
• README or docs updated to explain how to regenerate these files
• Consider adding a CI check to ensure these files stay up-to-date