react-manifest-rails 0.2.1 → 0.2.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 85ba6746290fd4cd708ac90748ef648429b162b84a7d63a36ddb74ae79f12d5a
-  data.tar.gz: 5d88bc95ea7f7500183bd5850936366414f39b1c8d85b153c1247b1640160eca
+  metadata.gz: '028416e61e2a4c385387c10267366155e596d434660c362c3f3e190ff984fa5d'
+  data.tar.gz: 7ab4143a3fee1f071da1450f28ba76a423986568a17401560dc68169539d390b
 SHA512:
-  metadata.gz: 4e581629322110b25163179454d47ad2c507a8df3481125561d33b67fa5158d5e85d8cbfb67bf970af2c94e38f84b9c163e7034fd8b28a8b6e22ece8edd25840
-  data.tar.gz: e8b77df28997e14466d541458f051ca77aadbb0d0adff7dc3160fbbd8dd2c4180d5eb5b5924f0b7586f92f16bb161e86247d3f244593f17b123e5d997836ec6a
+  metadata.gz: b24e547c5d9483781cf32fd081e897096907c81cf5de5e15cb1524917fba6766994def31416c7d50375c19c419c1d8168d5b3037df4004d28cafd876cdacc3f3
+  data.tar.gz: d94259f332e1fa63d9f2a37f9993576498d99eeac8f7338c7c3c5c236fcdd40e92a0aeabc900da34f0a953c8bbddcdf8367df121d9e13dd7143e761f1036ef44

data/CHANGELOG.md

@@ -5,6 +5,23 @@ 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.2.3] - 2026-04-15
+
+### Added
+- Compatibility entrypoint (`lib/react-manifest-rails.rb`) so default Bundler auto-require reliably loads the Railtie and rake tasks.
+- Development boot-time sync that generates missing `ux_*.js` manifests once on server start.
+- Configurable stdout logging with `config.stdout_logging` for visible generation events in development.
+
+### Changed
+- Streamlined README into a concise development-first quickstart with direct troubleshooting for missing tasks and watcher behavior.
+- Improved `react_manifest:generate` diagnostics when `ux_root` is missing or no controller bundles are detected.
+- Watcher and boot-time generation now emit clearer runtime status lines for easier debugging.
+
+## [0.2.2] - 2026-04-15
+
+### Changed
+- Lowered required Ruby version from >= 3.2.0 to >= 3.0.0
+
 ## [0.1.0] - 2026-04-13
 
 ### Added

data/README.md

@@ -1,353 +1,142 @@
 # react-manifest-rails
 
-**Zero-touch Sprockets manifest generation for react-rails apps**
+Generate per-controller Sprockets manifests for React code in Rails.
 
-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.
+This gem creates `ux_*.js` bundles and includes them with `react_bundle_tag`.
 
-## Features
+## Quick Start (Development)
 
-- **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`:
+1. Add gems:
 
 ```ruby
-gem 'react-manifest-rails'
+# Gemfile
+gem "react-manifest-rails"
+
+group :development do
+  gem "listen", "~> 3.0"
+end
 ```
 
-Then run:
+2. Install:
 
 ```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`:
+3. Add initializer:
 
 ```ruby
+# config/initializers/react_manifest.rb
+require "react_manifest"
+
 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.always_include = []
+  config.ignore = []
+  config.exclude_paths = ["react", "react_dev", "vendor"]
   config.size_threshold_kb = 500
+  config.dry_run = false
+  config.verbose = false
+  config.stdout_logging = true
 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
+4. Put React files under:
 
-### 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 %>
+```text
+app/assets/javascripts/ux/
+  app/
+    users/
+      users_index.jsx
+  components/
+    nav.jsx
 ```
 
-### With HTML options
+5. Include bundles in your layout:
 
 ```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
+<%= react_bundle_tag defer: true %>
 ```
 
-### Watch for changes (development)
+6. Start server:
 
 ```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
-
-## TypeScript / Custom Extensions
-
-By default the gem scans `*.js` and `*.jsx` files. To add TypeScript support:
-
-```ruby
-ReactManifest.configure do |config|
-  config.extensions = %w[js jsx ts tsx]
-end
+bundle exec rails s
 ```
 
-This affects file scanning, manifest generation, and the development file watcher.
-
-## File Watching (`listen` gem)
-
-The development file watcher requires the `listen` gem, which is **not** a hard dependency. If `listen` is absent the watcher is silently disabled and you must regenerate manifests manually.
-
-To enable watching, add `listen` to the development group in your app's `Gemfile`:
+In development:
+- If expected `ux_*.js` files are missing, the gem generates them once on boot.
+- If `listen` is installed, file changes regenerate manifests automatically.
+- If `listen` is missing, run `bundle exec rails react_manifest:generate` manually.
+- Set `config.stdout_logging = false` to silence ReactManifest console lines while keeping Rails logger output.
 
-```ruby
-gem "listen", "~> 3.0", group: :development
-```
+## What Gets Generated
 
-> **Note:** Changes to `config/initializers/react_manifest.rb` are not picked up by the watcher — you must restart the server after editing the initializer.
+- `ux_shared.js`: shared files outside `ux/app/`
+- `ux_<controller>.js`: one bundle per directory under `ux/app/`
 
-## Migrating an Existing `application.js`
+Example:
+- `ux/app/users/...` -> `ux_users.js`
+- `ux/app/admin/...` -> `ux_admin.js`
 
-If you are adding this gem to an app that already has a monolithic `application.js`, use the built-in migration tools:
+## Commands
 
-**Step 1 — Analyse what's there:**
+- Generate manifests now:
 
 ```bash
-rails react_manifest:analyze
+bundle exec rails react_manifest:generate
 ```
 
-This classifies each `//= require` line as `:vendor` (keep), `:ux_code` (remove), or `:unknown` (review manually). No files are modified.
-
-**Step 2 — Preview changes:**
+- Watch in foreground (debugging only; not required in normal dev):
 
 ```bash
-REACT_MANIFEST_DRY_RUN=1 rails react_manifest:migrate_application
+bundle exec rails react_manifest:watch
 ```
 
-**Step 3 — Apply changes:**
+- Print bundle size report:
 
 ```bash
-rails react_manifest:migrate_application
+bundle exec rails react_manifest:report
 ```
 
-A `.bak` backup is created next to each modified file before any write.
-
-**Step 4 — Generate bundles and verify:**
-
-```bash
-rails react_manifest:generate
-rails assets:precompile  # or just start the dev server
-```
-
-**Rolling back:** Simply restore the `.bak` file and remove the generated `ux_*.js` manifests.
-
 ## Troubleshooting
 
-### Bundle not being generated
-- Verify components live under `ux/app/<controller>/` (not directly under `ux/`)
-- Run `rails react_manifest:report` to see detected bundles
-- Check Rails logs for file watcher errors
+### `react_manifest:generate` is not recognized
 
-### Components not loading
-- Confirm `react_bundle_tag` is present in your layout
-- Check that the bundle name matches your controller path
-- Run `rails react_manifest:generate` to force regeneration
+Run:
 
-### Bundle appears more than once in HTML output
-- A bundle name in `config.always_include` that is also the controller bundle will be deduplicated automatically. Check whether both the shared bundle name and a specific bundle are listed in `always_include`.
-
-### Watcher stops responding
-- This is usually resolved by restarting the development server
-- Ensure the `listen` gem is installed (see above)
+```bash
+bundle exec rails -T | grep react_manifest
+```
 
-### Generator crashes on first run
-- Check that the process has write permission to `config.output_dir`
-- Verify `config.ux_root` exists; the generator is a no-op if the directory is missing
+If nothing appears:
+- Confirm the gem is in `Gemfile` and installed (`bundle show react-manifest-rails`).
+- Ensure the gem is not disabled with `require: false`.
+- Restart Spring/server (`bin/spring stop`, then re-run command).
 
-### Size warnings
-- The gem warns when bundles exceed `config.size_threshold_kb` (default 500 KB)
-- Consider splitting large controller directories or moving shared code into the shared bundle
-- Adjust the threshold: `config.size_threshold_kb = 1000`
+### Server starts but nothing happens
 
-## Performance
+Check these in order:
+- `app/assets/javascripts/ux` exists.
+- Your controller files are under `ux/app/<controller>/`.
+- Your layout includes `<%= react_bundle_tag %>`.
+- Run `bundle exec rails react_manifest:generate` once and check for generated `ux_*.js` in `app/assets/javascripts`.
 
-| Scenario | Typical time |
-|----------|-------------|
-| Initial generation (small project, ~20 controllers) | < 1 s |
-| Initial generation (large project, ~100 controllers) | 2–5 s |
-| Watcher debounce (regeneration after file change) | ~300 ms |
-| Memory overhead (symbol index, large project) | < 10 MB |
+### Auto-watch in dev does not run
 
-Scanning is purely regex-based — no Node.js or transpilation step required.
+- Ensure `listen` is in the development group.
+- Restart the Rails server after adding `listen`.
+- If you choose not to install `listen`, manual generation is the supported fallback.
 
 ## Compatibility
 
-| Dependency | Supported versions |
-|------------|-------------------|
-| Ruby | 3.2, 3.3 |
-| Rails / Railties | 6.1 – 8.x |
-| Sprockets | 3.x, 4.x |
-| listen (optional) | ~> 3.0 |
-
-> **Pre-1.0 notice:** The public API (configuration keys, rake task names, view helper signature) may change in minor versions until 1.0 is released. Pin to a patch version if stability is critical: `gem "react-manifest-rails", "~> 0.1.0"`.
-
-## Requirements
-
-- Ruby >= 3.2
-- Rails >= 6.1
-- Sprockets
-- react-rails
+- Ruby: 3.2+
+- Rails/Railties: 7.x to 8.x
+- Asset pipeline: Sprockets
 
 ## 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.
+MIT

data/lib/react-manifest-rails.rb

@@ -0,0 +1 @@
+require "react_manifest_rails"

data/lib/react_manifest/configuration.rb

@@ -41,6 +41,10 @@ module ReactManifest
     # Extra logging
     attr_accessor :verbose
 
+    # Emit ReactManifest status lines to stdout in development
+    # (independent from Rails.logger output)
+    attr_accessor :stdout_logging
+
     def initialize
       @ux_root           = "app/assets/javascripts/ux"
       @app_dir           = "app"
@@ -53,6 +57,7 @@ module ReactManifest
       @extensions        = %w[js jsx]
       @dry_run           = false
       @verbose           = false
+      @stdout_logging    = true
     end
 
     def dry_run?
@@ -63,6 +68,10 @@ module ReactManifest
       !!@verbose
     end
 
+    def stdout_logging?
+      !!@stdout_logging
+    end
+
     # Glob fragment used by Dir.glob, e.g. "*.{js,jsx}" or "*.{js,jsx,ts,tsx}"
     def extensions_glob
       "*.{#{extensions.join(',')}}"

data/lib/react_manifest/railtie.rb

@@ -2,6 +2,35 @@ require "rails/railtie"
 
 module ReactManifest
   class Railtie < Rails::Railtie
+    # ----------------------------------------------------------------
+    # In development, generate once on boot if expected manifests are missing.
+    # This makes first-run setup deterministic even before any file change event.
+    # ----------------------------------------------------------------
+    initializer "react_manifest.ensure_manifests" do
+      next unless Rails.env.development?
+
+      config = ReactManifest.configuration
+      missing = self.class.missing_manifest_bundles(config)
+      next if missing.empty?
+
+      message = "[ReactManifest] Missing manifests on boot: #{missing.join(', ')}. Generating now..."
+      Rails.logger&.info(message)
+      $stdout.puts(message) if config.stdout_logging?
+
+      begin
+        results = ReactManifest::Generator.new(config).run!
+        written = results.count { |r| r[:status] == :written }
+        unchanged = results.count { |r| r[:status] == :unchanged }
+        done = "[ReactManifest] Boot generation complete: #{written} written, #{unchanged} unchanged"
+        Rails.logger&.info(done)
+        $stdout.puts(done) if config.stdout_logging?
+      rescue StandardError => e
+        error = "[ReactManifest] Could not generate manifests on boot: #{e.message}"
+        Rails.logger&.warn(error)
+        $stdout.puts(error) if config.stdout_logging?
+      end
+    end
+
     # Expose config as Rails.application.config.react_manifest
     config.react_manifest = ReactManifest.configuration
 
@@ -12,6 +41,7 @@ module ReactManifest
       if Rails.env.development? && !ReactManifest::Watcher.running?
         begin
           ReactManifest::Watcher.start(ReactManifest.configuration)
+          Rails.logger&.info("[ReactManifest] Development watcher is active") if ReactManifest.configuration.verbose?
         rescue StandardError => e
           Rails.logger.warn "[ReactManifest] Could not start file watcher: #{e.message}"
         end
@@ -42,5 +72,21 @@ module ReactManifest
         Rake::Task["assets:precompile"].enhance(["react_manifest:generate"])
       end
     end
+
+    class << self
+      private
+
+      def missing_manifest_bundles(config)
+        output_dir = config.abs_output_dir
+        expected_manifest_bundles(config).reject do |bundle_name|
+          File.exist?(File.join(output_dir, "#{bundle_name}.js"))
+        end
+      end
+
+      def expected_manifest_bundles(config)
+        classification = ReactManifest::TreeClassifier.new(config).classify
+        ([config.shared_bundle] + classification.controller_dirs.map { |ctrl| ctrl[:bundle_name] }).uniq
+      end
+    end
   end
 end

data/lib/react_manifest/version.rb

@@ -1,3 +1,3 @@
 module ReactManifest
-  VERSION = "0.2.1".freeze
+  VERSION = "0.2.3".freeze
 end

data/lib/react_manifest/watcher.rb

@@ -65,6 +65,7 @@ module ReactManifest
         msg = "[ReactManifest] #{message}"
         if defined?(Rails) && Rails.logger
           Rails.logger.info(msg)
+          $stdout.puts(msg) if Rails.env.development? && ReactManifest.configuration.stdout_logging?
         else
           $stdout.puts msg
         end

data/tasks/react_manifest.rake

@@ -1,7 +1,15 @@
 namespace :react_manifest do
   desc "Generate all ux_*.js Sprockets manifests from the ux/ directory tree"
   task generate: :environment do
-    results = ReactManifest::Generator.new.run!
+    config = ReactManifest.configuration
+
+    unless Dir.exist?(config.abs_ux_root)
+      puts "[ReactManifest] ux_root not found: #{config.abs_ux_root}"
+      puts "[ReactManifest] Create it (for example: app/assets/javascripts/ux) then run this task again."
+      next
+    end
+
+    results = ReactManifest::Generator.new(config).run!
 
     written   = results.count { |r| r[:status] == :written }
     unchanged = results.count { |r| r[:status] == :unchanged }
@@ -12,6 +20,9 @@ namespace :react_manifest do
       puts "[ReactManifest] DRY-RUN complete: #{dry} manifest(s) would be written"
     else
       puts "[ReactManifest] Done: #{written} written, #{unchanged} unchanged, #{skipped} skipped"
+      if (written + unchanged + skipped).zero?
+        puts "[ReactManifest] No manifests generated. Ensure ux/app/<controller>/ contains .js or .jsx files."
+      end
     end
 
     # Print any scanner warnings

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: react-manifest-rails
 version: !ruby/object:Gem::Version
-  version: 0.2.1
+  version: 0.2.3
 platform: ruby
 authors:
 - Oliver Noonan
@@ -134,6 +134,7 @@ extra_rdoc_files: []
 files:
 - CHANGELOG.md
 - README.md
+- lib/react-manifest-rails.rb
 - lib/react_manifest.rb
 - lib/react_manifest/application_analyzer.rb
 - lib/react_manifest/application_migrator.rb
@@ -166,7 +167,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 3.2.0
+      version: 3.0.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="