react-manifest-rails 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: c76e23ad95cdf498e89dd0d63862c8d39b0acdf956df8dbf271a6157871e10f4
+  data.tar.gz: 68bb10eb5f7900798f4775db3399e9252879bdeb53e786b9d29e016e9e45600b
+SHA512:
+  metadata.gz: fdf7e42fb7ea57bfa28d818f53d387ac1dc6fbeb8015bf34a563fd095f1cd70edd966013a36996fe864f56d2fc3c21c97030b136f6b547d317a2555998484198
+  data.tar.gz: 36055fab58f773760266ad9e706a52dfe71e333e0dbd3e61db234e65095cb54709b82b031071ca78576db54ed9afb042ab72a232496c24bb5defd058f6169f63

data/CHANGELOG.md

@@ -0,0 +1,22 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] - 2026-04-13
+
+### Added
+- Initial release of react-manifest-rails gem
+- Zero-touch Sprockets manifest generation for react-rails applications
+- Automatic per-controller bundle generation (`ux_*.js` manifests)
+- File watcher for development that regenerates bundles on file changes
+- Smart `react_bundle_tag` view helper for automatic bundle selection
+- Intelligent bundle resolution for namespaced controllers
+- Automatic shared bundle generation for common dependencies
+- Configuration system with sensible defaults
+- Integration with Rails' `assets:precompile` for production deployments
+- Comprehensive README with setup instructions and usage examples
+- Bundle size warnings to catch oversized bundles
+- Support for Rails 6.1+ and Ruby 2.6+

data/README.md

@@ -0,0 +1,244 @@
+# react-manifest-rails
+
+**Zero-touch Sprockets manifest generation for react-rails apps**
+
+A Rails gem that automatically generates lean, controller-specific JavaScript bundles for applications using `react-rails` and Sprockets, eliminating the need for monolithic `application.js` files.
+
+## Features
+
+- **Automatic bundle generation**: Creates per-controller `ux_*.js` manifests on-demand
+- **Smart file watching**: Automatically regenerates bundles when files change in development
+- **Intelligent bundle resolution**: The `react_bundle_tag` view helper automatically selects the correct bundles for each controller
+- **Namespace-aware**: Handles nested controllers and namespaces gracefully (e.g., `admin/users` → `ux_admin_users`)
+- **Shared bundles**: Automatically extracts shared dependencies into a `ux_shared` bundle
+- **Always-include bundles**: Configure bundles that should be loaded on every page
+- **Production-ready**: Integrates seamlessly with `assets:precompile` for CI/production deployments
+- **Zero configuration**: Works out-of-the-box with sensible defaults for standard Rails projects
+
+## Advantages
+
+### 1. Smaller Bundle Sizes
+Instead of a single monolithic `application.js` that loads all React components for the entire app, each controller gets its own lean bundle containing only the components it needs. This means:
+- **Faster page loads**: Users only download what they need
+- **Better caching**: Components unchanged on their page won't bust the cache
+- **Reduced bandwidth**: Particularly beneficial for mobile users
+
+### 2. Simplified Development
+- **Automatic regeneration**: Changes to component files are automatically bundled—no manual build steps
+- **No configuration needed**: Works with standard Rails directory structures immediately
+- **Easy integration**: Drop the gem in and it works with your existing `react-rails` setup
+
+### 3. Production Reliability
+- **CI/CD friendly**: Integrates with `assets:precompile` for automated deployments
+- **Deterministic builds**: Consistent bundle generation across environments
+- **Safety checks**: Warns about oversized bundles to catch potential issues
+
+### 4. Developer Experience
+- **Per-controller organization**: Bundle structure mirrors your Rails controller layout
+- **Smart bundle selection**: View helper automatically picks the right bundles—no manual tag management
+- **Clear visibility**: Built-in reporter shows exactly what's in each bundle
+
+## Installation
+
+Add the gem to your `Gemfile`:
+
+```ruby
+gem 'react-manifest-rails'
+```
+
+Then run:
+
+```bash
+bundle install
+```
+
+## Setup
+
+### 1. Create your UX directory structure
+
+By default, the gem expects your React components to live in `app/assets/javascripts/ux/`. You should organize it like this:
+
+```
+app/assets/javascripts/ux/
+├── app/                          # Per-controller components (becomes ux_*.js bundles)
+│   ├── users/
+│   │   ├── UserCard.jsx
+│   │   └── UserList.jsx
+│   ├── products/
+│   │   └── ProductGrid.jsx
+│   └── dashboard/
+│       └── Dashboard.jsx
+├── shared/                        # Shared utilities (becomes ux_shared)
+│   ├── api.js
+│   └── utils.js
+└── components/                    # Global components (becomes ux_shared)
+    └── Navigation.jsx
+```
+
+### 2. Configure the gem (Optional)
+
+Create an initializer at `config/initializers/react_manifest.rb`:
+
+```ruby
+ReactManifest.configure do |config|
+  # Where your UX root lives (default: "app/assets/javascripts/ux")
+  config.ux_root = "app/assets/javascripts/ux"
+
+  # Subdir within ux_root containing per-controller components (default: "app")
+  config.app_dir = "app"
+
+  # Where generated manifests are written (default: "app/assets/javascripts")
+  config.output_dir = "app/assets/javascripts"
+
+  # Name of the shared bundle (default: "ux_shared")
+  config.shared_bundle = "ux_shared"
+
+  # Bundles to always include on every page (default: [])
+  # config.always_include = ["ux_main"]
+
+  # Directories within app_dir to ignore (default: [])
+  # config.ignore = ["internal_tools"]
+
+  # Warn if any bundle exceeds this size in KB (default: 500, 0 to disable)
+  config.size_threshold_kb = 500
+end
+```
+
+### 3. Use the view helper
+
+In your layout template (`app/views/layouts/application.html.erb` or similar):
+
+```erb
+<head>
+  <%= javascript_include_tag "application" %>
+  <%= react_bundle_tag defer: true %>
+</head>
+```
+
+The `react_bundle_tag` helper automatically:
+1. Includes the shared bundle (`ux_shared`)
+2. Includes any bundles in `config.always_include`
+3. Includes the controller-specific bundle (e.g., `ux_users` for UsersController)
+4. Returns an empty string gracefully if there's no matching bundle
+
+## How It Works
+
+### Bundle Generation
+
+The gem scans your `app/assets/javascripts/ux/` directory and generates Sprockets manifests:
+
+- **Controller-specific bundles**: Each directory under `ux/app/` becomes a bundle
+  - `ux/app/users/` → `ux_users.js`
+  - `ux/app/admin/reports/` → `ux_admin_reports.js`
+
+- **Shared bundle**: Everything outside `ux/app/` (e.g., `shared/`, `components/`) automatically goes into `ux_shared.js`
+
+- **Dependency tracking**: The gem analyzes dependencies to prevent duplication across bundles
+
+### Development
+
+In development, a file watcher automatically:
+- Detects changes to component files
+- Regenerates affected bundles
+- Updates manifests in real-time
+
+### Production
+
+The gem integrates with Rails' `assets:precompile` task:
+
+```bash
+rails assets:precompile
+```
+
+This ensures all bundles are generated before deployment.
+
+## View Helper Usage
+
+### Basic usage
+
+```erb
+<%= react_bundle_tag %>
+```
+
+### With HTML options
+
+```erb
+<%= react_bundle_tag defer: true, async: true %>
+```
+
+### Automatic resolution
+
+The helper automatically resolves bundles based on `controller_path`:
+
+| Controller | Resolved Bundles |
+|-----------|------------------|
+| UsersController | ux_shared + ux_users |
+| Admin::ReportsController | ux_shared + ux_admin_reports (or ux_admin if not found) |
+| Pages::LandingController | ux_shared + ux_pages_landing (or ux_pages, or ux_landing) |
+
+## Rake Tasks
+
+### Generate bundles (one-time)
+
+```bash
+rails react_manifest:generate
+```
+
+### Watch for changes (development)
+
+```bash
+rails react_manifest:watch
+```
+
+### Show bundle contents
+
+```bash
+rails react_manifest:report
+```
+
+## Configuration Reference
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `ux_root` | `"app/assets/javascripts/ux"` | Root directory of your React components |
+| `app_dir` | `"app"` | Subdirectory of `ux_root` for per-controller components |
+| `output_dir` | `"app/assets/javascripts"` | Where generated manifests are written |
+| `shared_bundle` | `"ux_shared"` | Name of the shared bundle |
+| `always_include` | `[]` | Array of bundle names to load on every page |
+| `ignore` | `[]` | Directories to skip during scanning |
+| `exclude_paths` | `["react", "react_dev", "vendor"]` | Top-level directories to exclude |
+| `size_threshold_kb` | `500` | Warn if a bundle exceeds this size (0 = disabled) |
+| `dry_run` | `false` | Print what would change without writing files |
+| `verbose` | `false` | Enable extra logging |
+
+## Troubleshooting
+
+### Bundle not being generated
+- Check that your components are in the correct directory structure (`app/assets/javascripts/ux/app/...`)
+- Run `rails react_manifest:report` to see what bundles were detected
+- Check Rails logs for any file watcher errors
+
+### Components not loading
+- Verify `react_bundle_tag` is in your layout
+- Check that the bundle name matches your controller path
+- Make sure components are in the `ux/` directory, not elsewhere
+
+### Size warnings
+- The gem warns when bundles exceed 500KB
+- Consider splitting large bundles into smaller, more focused ones
+- Adjust `config.size_threshold_kb` in your initializer if needed
+
+## Requirements
+
+- Ruby >= 2.6.0
+- Rails >= 6.1
+- Sprockets
+- react-rails
+
+## License
+
+MIT License. See LICENSE for details.
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/olivernoonan/react-manifest-rails.

data/lib/react_manifest/application_analyzer.rb

@@ -0,0 +1,150 @@
+module ReactManifest
+  # Analyzes existing application*.js files to classify each directive as:
+  #   :vendor   — vendor lib require (keep)
+  #   :ux_code  — UX/app code require (remove — will be served by ux_*.js bundles)
+  #   :unknown  — needs manual review
+  #
+  # Produces a human-readable report without writing anything.
+  class ApplicationAnalyzer
+    DIRECTIVE_PATTERN = /^\s*\/\/=\s+(require(?:_tree|_directory)?)\s+(.+)$/.freeze
+
+    # Libs we recognise as vendor (case-insensitive partial match on the require path)
+    VENDOR_HINTS = %w[
+      react react-dom react_dom reactdom
+      mui material-ui
+      redux redux-thunk
+      axios lodash underscore
+      jquery backbone handlebars
+      turbo stimulus
+      vendor
+    ].freeze
+
+    ClassifiedDirective = Struct.new(:original_line, :directive, :path, :classification, :note, keyword_init: true)
+
+    Result = Struct.new(:file, :directives, keyword_init: true) do
+      def vendor_lines;   directives.select { |d| d.classification == :vendor };   end
+      def ux_code_lines;  directives.select { |d| d.classification == :ux_code };  end
+      def unknown_lines;  directives.select { |d| d.classification == :unknown };  end
+      def clean?;         ux_code_lines.empty? && unknown_lines.empty?;             end
+    end
+
+    def initialize(config = ReactManifest.configuration)
+      @config = config
+    end
+
+    # Returns array of Result objects, one per application*.js found
+    def analyze
+      application_files.map { |f| analyze_file(f) }
+    end
+
+    # Pretty-print the analysis report to stdout
+    def print_report(results = analyze)
+      puts "\n=== ReactManifest: Application Manifest Analysis ===\n"
+
+      if results.empty?
+        puts "No application*.js files found in #{@config.abs_output_dir}"
+        return
+      end
+
+      results.each do |result|
+        rel = result.file.sub(Rails.root.to_s + "/", "")
+        status = result.clean? ? "✓ already clean" : "⚠ needs migration"
+        puts "\n#{rel} [#{status}]"
+        puts "-" * 60
+
+        result.directives.each do |d|
+          icon = case d.classification
+                 when :vendor   then "  ✓ KEEP   "
+                 when :ux_code  then "  ✗ REMOVE "
+                 when :unknown  then "  ? REVIEW "
+                 end
+          puts "#{icon} #{d.original_line.strip}"
+          puts "           → #{d.note}" if d.note
+        end
+      end
+
+      puts "\n"
+      puts "Run `rails react_manifest:migrate_application` to apply changes."
+      puts "Use `--dry-run` (or config.dry_run = true) to preview first.\n\n"
+    end
+
+    private
+
+    def application_files
+      Dir.glob(File.join(@config.abs_output_dir, "application*.js"))
+         .reject { |f| f.end_with?(".bak") }
+         .sort
+    end
+
+    def analyze_file(file_path)
+      directives = []
+
+      File.foreach(file_path, encoding: "utf-8") do |line|
+        raw = line.chomp
+        match = raw.match(DIRECTIVE_PATTERN)
+
+        unless match
+          # Non-directive lines (comments, blank) — pass through as :vendor (keep)
+          directives << ClassifiedDirective.new(
+            original_line:  raw,
+            directive:      nil,
+            path:           nil,
+            classification: :passthrough,
+            note:           nil
+          )
+          next
+        end
+
+        directive = match[1]  # require, require_tree, require_directory
+        path      = match[2].strip
+
+        classification, note = classify_directive(directive, path)
+
+        directives << ClassifiedDirective.new(
+          original_line:  raw,
+          directive:      directive,
+          path:           path,
+          classification: classification,
+          note:           note
+        )
+      end
+
+      Result.new(file: file_path, directives: directives)
+    end
+
+    def classify_directive(directive, path)
+      # require_tree is almost always too greedy
+      if directive.include?("tree") || directive.include?("directory")
+        if path_is_ux?(path)
+          return [:ux_code, "require_tree over ux/ — will be replaced by ux_*.js bundles"]
+        else
+          return [:unknown, "require_tree/require_directory — review manually: #{path}"]
+        end
+      end
+
+      # Explicit require
+      if path_is_ux?(path)
+        return [:ux_code, "ux/ code — will be served by ux_*.js bundles"]
+      end
+
+      if path_is_vendor?(path)
+        return [:vendor, nil]
+      end
+
+      [:unknown, "Could not auto-classify — review manually"]
+    end
+
+    def path_is_ux?(path)
+      ux_prefix = @config.ux_root.split("/").last  # e.g. "ux"
+      path.include?(ux_prefix) ||
+        path.start_with?("./ux") ||
+        path.start_with?("ux/")
+    end
+
+    def path_is_vendor?(path)
+      normalised = path.downcase
+      VENDOR_HINTS.any? { |hint| normalised.include?(hint) } ||
+        @config.exclude_paths.any? { |ep| normalised.include?(ep.downcase) }
+    end
+  end
+end

data/lib/react_manifest/application_migrator.rb

@@ -0,0 +1,101 @@
+module ReactManifest
+  # Rewrites application*.js files to remove UX/app code requires,
+  # keeping only vendor lib requires.
+  #
+  # Safety:
+  #   - Creates a .bak backup before any write; aborts if backup fails
+  #   - Dry-run mode: prints what would change, writes nothing
+  #   - Never removes :vendor or :passthrough lines
+  #   - Adds a managed-by comment at the top
+  class ApplicationMigrator
+    MANAGED_COMMENT = <<~JS
+      // Vendor libraries — loaded on every page.
+      // React app code is now served per-controller via react_bundle_tag.
+      // Managed by react-manifest-rails — do not add require_tree.
+    JS
+
+    def initialize(config = ReactManifest.configuration)
+      @config   = config
+      @analyzer = ApplicationAnalyzer.new(config)
+    end
+
+    # Migrate all application*.js files. Returns array of {file:, status:} hashes.
+    def migrate!
+      results = @analyzer.analyze
+
+      if results.empty?
+        $stdout.puts "[ReactManifest] No application*.js files found to migrate."
+        return []
+      end
+
+      results.map do |result|
+        if result.clean?
+          $stdout.puts "[ReactManifest] #{short(result.file)} — already clean, skipping."
+          { file: result.file, status: :already_clean }
+        else
+          rewrite(result)
+        end
+      end
+    end
+
+    private
+
+    def rewrite(result)
+      file        = result.file
+      new_content = build_new_content(result)
+
+      if @config.dry_run?
+        $stdout.puts "\n[ReactManifest] DRY-RUN: #{short(file)}"
+        print_diff(file, new_content)
+        return { file: file, status: :dry_run }
+      end
+
+      # Backup first — abort if backup cannot be created to avoid data loss.
+      bak_path = "#{file}.bak"
+      begin
+        FileUtils.cp(file, bak_path)
+        $stdout.puts "[ReactManifest] Backup: #{short(bak_path)}"
+      rescue => e
+        $stdout.puts "[ReactManifest] ERROR: Could not create backup of #{short(file)}: #{e.message}"
+        $stdout.puts "[ReactManifest] Migration aborted for #{short(file)} — original file unchanged."
+        return { file: file, status: :backup_failed, error: e.message }
+      end
+
+      File.write(file, new_content, encoding: "utf-8")
+      $stdout.puts "[ReactManifest] Migrated: #{short(file)}"
+
+      { file: file, status: :migrated, backup: bak_path }
+    end
+
+    def build_new_content(result)
+      kept_lines = result.directives
+        .select { |d| %i[vendor passthrough].include?(d.classification) }
+        .map(&:original_line)
+
+      # Remove leading blank lines from kept_lines
+      kept_lines.shift while kept_lines.first&.strip&.empty?
+
+      lines = []
+      lines << MANAGED_COMMENT
+      lines += kept_lines
+      lines << ""  # trailing newline
+
+      lines.join("\n")
+    end
+
+    def print_diff(file, new_content)
+      old_lines = File.readlines(file, encoding: "utf-8").map(&:chomp)
+      new_lines = new_content.lines.map(&:chomp)
+
+      removed = old_lines - new_lines
+      added   = new_lines - old_lines
+
+      removed.each { |l| $stdout.puts "  - #{l}" }
+      added.each   { |l| $stdout.puts "  + #{l}" }
+    end
+
+    def short(path)
+      path.to_s.sub(Rails.root.to_s + "/", "")
+    end
+  end
+end

data/lib/react_manifest/configuration.rb

@@ -0,0 +1,67 @@
+module ReactManifest
+  class Configuration
+    # Root of the ux/ tree to scan (relative to Rails.root)
+    attr_accessor :ux_root
+
+    # Subdir within ux_root that contains per-controller JSX
+    attr_accessor :app_dir
+
+    # Where generated ux_*.js manifests are written (relative to Rails.root)
+    attr_accessor :output_dir
+
+    # Bundle name for auto-generated shared bundle (all non-app/ dirs)
+    attr_accessor :shared_bundle
+
+    # Bundles always prepended by react_bundle_tag (e.g. ["ux_main"])
+    attr_accessor :always_include
+
+    # Directories under app_dir to completely ignore
+    attr_accessor :ignore
+
+    # Top-level dirs under output_dir to never scan (vendor libs, etc.)
+    attr_accessor :exclude_paths
+
+    # Warn if a bundle exceeds this size in KB (0 = disabled)
+    attr_accessor :size_threshold_kb
+
+    # Print what would change, write nothing
+    attr_accessor :dry_run
+
+    # Extra logging
+    attr_accessor :verbose
+
+    def initialize
+      @ux_root           = "app/assets/javascripts/ux"
+      @app_dir           = "app"
+      @output_dir        = "app/assets/javascripts"
+      @shared_bundle     = "ux_shared"
+      @always_include    = []
+      @ignore            = []
+      @exclude_paths     = %w[react react_dev vendor]
+      @size_threshold_kb = 500
+      @dry_run           = false
+      @verbose           = false
+    end
+
+    def dry_run?
+      !!@dry_run
+    end
+
+    def verbose?
+      !!@verbose
+    end
+
+    # Absolute path helpers (requires Rails.root to be set)
+    def abs_ux_root
+      Rails.root.join(ux_root).to_s
+    end
+
+    def abs_app_dir
+      File.join(abs_ux_root, app_dir)
+    end
+
+    def abs_output_dir
+      Rails.root.join(output_dir).to_s
+    end
+  end
+end

data/lib/react_manifest/dependency_map.rb

@@ -0,0 +1,52 @@
+module ReactManifest
+  # Wraps scanner results into a queryable dependency map.
+  # Used by the analyze rake task and reporter for diagnostics.
+  class DependencyMap
+    attr_reader :symbol_index, :controller_usages, :warnings
+
+    def initialize(scan_result)
+      @symbol_index      = scan_result.symbol_index
+      @controller_usages = scan_result.controller_usages
+      @warnings          = scan_result.warnings
+    end
+
+    # All shared files used by the given controller
+    def shared_files_for(controller_name)
+      @controller_usages.fetch(controller_name, [])
+    end
+
+    # Which controllers use a given shared file
+    def controllers_using(shared_file)
+      @controller_usages.select { |_, files| files.include?(shared_file) }.keys
+    end
+
+    # Symbols defined in shared dirs
+    def all_symbols
+      @symbol_index.keys
+    end
+
+    # Pretty-print for the analyze rake task
+    def print_report
+      puts "\n=== ReactManifest Dependency Analysis ===\n\n"
+
+      puts "Shared Symbol Index (#{@symbol_index.size} symbols):"
+      @symbol_index.each do |sym, file|
+        puts "  #{sym.ljust(40)} #{file}"
+      end
+
+      puts "\nPer-Controller Usage:"
+      @controller_usages.each do |ctrl, files|
+        puts "\n  [#{ctrl}] (#{files.size} shared references)"
+        files.each { |f| puts "    #{f}" }
+        puts "    (none)" if files.empty?
+      end
+
+      unless @warnings.empty?
+        puts "\nWarnings (#{@warnings.size}):"
+        @warnings.each { |w| puts "  ⚠  #{w}" }
+      end
+
+      puts "\n"
+    end
+  end
+end