iron_admin 0.4.1 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6a7e6f008423227296c7d793dc516a5e535249bedececc1c41af83dd91a019d4
-  data.tar.gz: 1eb8f4c673a35d21fd1f04bc38fa72d55fba0e984cccc965156bc273f9696ab3
+  metadata.gz: a0ecb90c4ba9e2c3f605ceae6041d3b73ba81ebf8cf39814d07a01d879c3a005
+  data.tar.gz: 36979178db1f62372e1ca1d660ad86c8696729db3cc6831326df7747789bb331
 SHA512:
-  metadata.gz: 7259b141211a0575f49d8df3dc3f22fc3d421b0ef60a31770b26aff5da46da70d566a8e6c4255723f836ce7995c39ea4b5764a036dc96157b42004897d52aade
-  data.tar.gz: fb326e0e209721a1341c8b0740325f2129a5d8e66de8ba2697f3e6325a271227961128c786c25574c88006333c4887c3d805055584284c7589ac925290c45ef3
+  metadata.gz: e8dbf2accd69aa53038df74fb9e5a080581b9cd70d45cc5af806a13df2934ffe072da678ed81fb22c9b3354274e4997ccf5b335f5ac140eab3a54c55aaf8d697
+  data.tar.gz: d8d3fbf9c74c876dc85837ebbf5f767ae68eb3246e6fb543b17baf8e9d196a33b45505489660ff73816699de9054c2d7cc04611f78668af0af7ae754a07b6e66

data/README.md

@@ -20,6 +20,7 @@ Convention-over-configuration admin panel engine for Ruby on Rails. Build beauti
 
 - Ruby >= 3.2
 - Rails >= 7.1
+- [tailwindcss-rails](https://github.com/rails/tailwindcss-rails) >= 4.0
 
 ## Installation
 
@@ -27,6 +28,7 @@ Add to your Gemfile:
 
 ```ruby
 gem "iron_admin"
+gem "tailwindcss-rails"
 ```
 
 Then run:
@@ -36,14 +38,40 @@ bundle install
 rails generate iron_admin:install
 ```
 
-Mount the engine in your `config/routes.rb`:
+The install generator will:
+- Create `app/iron_admin/resources/` and `app/iron_admin/dashboards/` directories
+- Add a configuration initializer at `config/initializers/iron_admin.rb`
+- Create a sample dashboard
+- Mount the engine at `/admin` in your routes
+- Add the IronAdmin Tailwind CSS import to your `app/assets/tailwind/application.css`
 
-```ruby
-Rails.application.routes.draw do
-  mount IronAdmin::Engine, at: "/admin"
-end
+### Tailwind CSS Setup
+
+IronAdmin uses Tailwind CSS v4 for all styling. The `tailwindcss-rails` gem handles
+compilation. After running the install generator, your `app/assets/tailwind/application.css`
+should include:
+
+```css
+@import "tailwindcss";
+@import "../builds/tailwind/iron_admin";
+```
+
+The second line imports IronAdmin's `@source` directives so the Tailwind compiler
+scans the engine's views and components for CSS classes. Without it, the admin panel
+will render unstyled.
+
+If you're setting up manually (without the generator), run:
+
+```bash
+rails tailwindcss:build
 ```
 
+Then verify that `app/assets/builds/tailwind/iron_admin.css` was created. If not,
+check that `tailwindcss-rails` >= 4.0 is installed and that the engine gem is properly
+loaded.
+
+For development, use `bin/dev` or `rails tailwindcss:watch` to recompile CSS on changes.
+
 ## Quick Start
 
 ### 1. Configure Authentication
@@ -75,26 +103,30 @@ rails generate iron_admin:resource Order
 ### 3. Customize Resources
 
 ```ruby
-# app/iron_admin/user_resource.rb
-class UserResource < IronAdmin::Resource
-  field :role, type: :badge, colors: { admin: :purple, user: :blue }
-  field :email, type: :text
+# app/iron_admin/resources/user_resource.rb
+module IronAdmin
+  module Resources
+    class UserResource < IronAdmin::Resource
+      field :role, type: :badge, colors: { admin: :purple, user: :blue }
+      field :email, type: :text
 
-  searchable :name, :email
+      searchable :name, :email
 
-  filter :role, type: :select, choices: User.roles.keys
-  filter :created_at, type: :date_range
+      filter :role, type: :select, choices: User.roles.keys
+      filter :created_at, type: :date_range
 
-  scope :admins, -> { where(role: :admin) }
-  scope :recent, -> { where("created_at > ?", 7.days.ago) }
+      scope :admins, -> { where(role: :admin) }
+      scope :recent, -> { where("created_at > ?", 7.days.ago) }
 
-  index_fields :id, :name, :email, :role, :created_at
-  form_fields :name, :email, :role
+      index_fields :id, :name, :email, :role, :created_at
+      form_fields :name, :email, :role
 
-  menu priority: 1, icon: "users", group: "People"
+      menu priority: 1, icon: "users", group: "People"
 
-  action :lock, icon: "lock-closed", confirm: true do |record|
-    record.update!(locked_at: Time.current)
+      action :lock, icon: "lock-closed", confirm: true do |record|
+        record.update!(locked_at: Time.current)
+      end
+    end
   end
 end
 ```
@@ -102,18 +134,22 @@ end
 ### 4. Create a Dashboard
 
 ```ruby
-# app/iron_admin/admin_dashboard.rb
-class AdminDashboard < IronAdmin::Dashboard
-  metric :total_users, format: :number do
-    User.count
+# app/iron_admin/dashboards/admin_dashboard.rb
+module IronAdmin
+  module Dashboards
+    class AdminDashboard < IronAdmin::Dashboard
+      metric :total_users, format: :number do
+        User.count
+      end
+
+      metric :monthly_revenue, format: :currency do
+        Payment.where("created_at > ?", 30.days.ago).sum(:amount)
+      end
+
+      recent :users, limit: 5, scope: -> { order(created_at: :desc) }
+      recent :payments, limit: 5
+    end
   end
-
-  metric :monthly_revenue, format: :currency do
-    Payment.where("created_at > ?", 30.days.ago).sum(:amount)
-  end
-
-  recent :users, limit: 5, scope: -> { order(created_at: :desc) }
-  recent :payments, limit: 5
 end
 ```
 

data/docs/getting-started/installation.md

@@ -4,18 +4,15 @@
 
 - Ruby >= 3.2
 - Rails >= 7.1
-- Tailwind CSS (for default theme classes)
+- [tailwindcss-rails](https://github.com/rails/tailwindcss-rails) >= 4.0
 
-## Step 1: Add the Gem
+## Step 1: Add the Gems
 
-Add IronAdmin to your `Gemfile`:
+Add IronAdmin and `tailwindcss-rails` to your `Gemfile`:
 
 ```ruby
-# From a local path:
-gem "iron_admin", path: "/path/to/iron_admin"
-
-# Or if published to a gem server:
 gem "iron_admin"
+gem "tailwindcss-rails"
 ```
 
 Then run:
@@ -35,11 +32,13 @@ This creates:
 | File | Purpose |
 |------|---------|
 | `config/initializers/iron_admin.rb` | Main configuration (title, auth, theme) |
-| `app/iron_admin/dashboards/` | Directory for dashboard definitions |
 | `app/iron_admin/resources/` | Directory for resource definitions |
-| `app/iron_admin/dashboard.rb` | Default dashboard class |
+| `app/iron_admin/dashboards/` | Directory for dashboard definitions |
+| `app/iron_admin/dashboards/admin_dashboard.rb` | Default dashboard class |
 
-It also mounts the engine in `config/routes.rb`.
+It also:
+- Mounts the engine at `/admin` in `config/routes.rb`
+- Adds the IronAdmin CSS import to `app/assets/tailwind/application.css`
 
 ## Step 3: Mount the Engine (if not auto-mounted)
 
@@ -79,9 +78,107 @@ rails generate iron_admin:resource User
 
 This creates `app/iron_admin/resources/user_resource.rb`. IronAdmin automatically infers fields from your model's database schema.
 
-## Step 6: Visit the Admin Panel
+## Step 6: Build CSS and Start the Server
+
+```bash
+rails tailwindcss:build
+bin/rails server
+```
+
+Visit `/admin` and your admin panel is ready.
+
+For development with live CSS recompilation, use `bin/dev` (which runs
+`tailwindcss:watch` alongside the Rails server via foreman).
+
+> **Note:** There is a [known issue](https://github.com/rails/tailwindcss-rails/issues/602)
+> in `tailwindcss-rails` v4 where `bin/dev` exits immediately after
+> starting. If this happens, edit `Procfile.dev` and change the CSS line
+> to `css: bin/rails tailwindcss:watch[always]`. See
+> [Troubleshooting](../guides/troubleshooting.md#bindev-exits-immediately-after-starting)
+> for details.
+
+## Tailwind CSS Setup
+
+IronAdmin uses Tailwind CSS v4 for all styling via the `tailwindcss-rails` gem.
+Understanding how the CSS pipeline works will help you troubleshoot any styling issues.
+
+### How it works
+
+1. IronAdmin ships with `@source` directives at `app/assets/tailwind/iron_admin/engine.css`
+   inside the gem. These tell the Tailwind compiler where to scan for CSS utility classes
+   used by the engine's views, components, and helpers.
+
+2. When `tailwindcss:build` runs, it first executes `tailwindcss:engines`. This task
+   detects IronAdmin's engine CSS and creates a bridge file at
+   `app/assets/builds/tailwind/iron_admin.css` containing an `@import` that points
+   to the engine's CSS.
+
+3. Your `app/assets/tailwind/application.css` must import this bridge file:
+
+   ```css
+   @import "tailwindcss";
+   @import "../builds/tailwind/iron_admin";
+   ```
+
+4. The Tailwind compiler processes `application.css`, follows the imports, scans all
+   the engine's source files via the `@source` directives, and generates the final
+   `app/assets/builds/tailwind.css` with all necessary utility classes.
+
+5. The engine's layout references `stylesheet_link_tag "tailwind"`, which serves
+   this compiled CSS file.
+
+### Manual setup (without the generator)
+
+If you didn't use the install generator, or the import line is missing:
 
-Start your server and navigate to `/admin`.
+1. Verify `tailwindcss-rails` is in your Gemfile and installed
+2. Add the import to `app/assets/tailwind/application.css`:
+
+   ```css
+   @import "tailwindcss";
+   @import "../builds/tailwind/iron_admin";
+   ```
+
+3. Build the CSS:
+
+   ```bash
+   rails tailwindcss:build
+   ```
+
+4. Verify the build output:
+
+   ```bash
+   ls -la app/assets/builds/tailwind.css
+   # Should be ~30KB+ (not ~6KB which indicates no utility classes)
+   ```
+
+### Troubleshooting
+
+**Styles not loading (unstyled admin panel)**
+
+This almost always means the Tailwind compiler didn't scan IronAdmin's source files.
+Check:
+
+1. The `@import "../builds/tailwind/iron_admin"` line exists in
+   `app/assets/tailwind/application.css`
+2. The bridge file exists at `app/assets/builds/tailwind/iron_admin.css`
+   (run `rails tailwindcss:build` to regenerate it)
+3. The compiled CSS at `app/assets/builds/tailwind.css` is large enough
+   (~30KB+, not ~6KB)
+
+**Bridge file not generated**
+
+If `app/assets/builds/tailwind/iron_admin.css` doesn't exist after running
+`rails tailwindcss:build`:
+
+- Ensure `tailwindcss-rails` >= 4.0 is installed (`bundle info tailwindcss-rails`)
+- Ensure `iron_admin` is properly loaded (check `bundle info iron_admin`)
+- Try running `rails tailwindcss:engines` directly
+
+**Styles disappear after bundle update**
+
+The bridge file uses an absolute path to the gem's CSS. After updating the gem
+(which changes the gem path), run `rails tailwindcss:build` to regenerate it.
 
 ## Dependencies
 
@@ -97,19 +194,8 @@ IronAdmin depends on the following gems (installed automatically):
 | `haml-rails` | >= 2.0 | Template engine |
 | `heroicon` | >= 1.0 | SVG icons |
 
-## Tailwind CSS Setup
-
-IronAdmin uses Tailwind CSS classes for all styling. Ensure your Tailwind configuration includes the engine's view paths in the `content` array so that all CSS classes are properly compiled.
+**Peer dependency** (must be added to your Gemfile manually):
 
-Add the path to the engine's app directory in your `tailwind.config.js`:
-
-```js
-module.exports = {
-  content: [
-    // ... your app paths
-    "./path/to/iron_admin/app/**/*.{rb,haml}",
-  ],
-}
-```
-
-If installed as a gem, use `bundle show iron_admin` to find the installed path and add it to your Tailwind content paths.
+| Gem | Version | Purpose |
+|-----|---------|---------|
+| `tailwindcss-rails` | >= 4.0 | Tailwind CSS compilation |

data/docs/guides/troubleshooting.md

@@ -22,19 +22,48 @@ Common issues and their solutions.
 mount IronAdmin::Engine => "/admin"
 ```
 
-### Assets/CSS not loading
+### Assets/CSS not loading (unstyled admin panel)
 
-**Cause:** Tailwind CSS not configured to scan IronAdmin files.
+**Cause:** The Tailwind compiler didn't scan IronAdmin's source files.
 
-**Solution:** Add to `tailwind.config.js`:
-```javascript
-content: [
-  // ... your paths
-  "./path/to/iron_admin/app/**/*.{rb,haml}",
-]
+**Solutions:**
+
+1. Verify the import line exists in `app/assets/tailwind/application.css`:
+   ```css
+   @import "tailwindcss";
+   @import "../builds/tailwind/iron_admin";
+   ```
+2. Check the bridge file exists at `app/assets/builds/tailwind/iron_admin.css`
+   (run `rails tailwindcss:build` to regenerate it)
+3. Verify the compiled CSS is large enough (~30KB+, not ~6KB):
+   ```bash
+   ls -la app/assets/builds/tailwind.css
+   ```
+
+See the [Installation guide](../getting-started/installation.md#tailwind-css-setup) for full
+details on how the CSS pipeline works.
+
+### `bin/dev` exits immediately after starting
+
+**Cause:** This is a known upstream issue in `tailwindcss-rails` ([#602](https://github.com/rails/tailwindcss-rails/issues/602)).
+The Tailwind CSS v4 binary's `--watch` flag exits when stdin is closed.
+Foreman (used by `bin/dev`) does not provide a TTY to child processes, so the
+watcher receives EOF on stdin and terminates. Since foreman treats any child
+exit as a signal to shut down all processes, the entire `bin/dev` stack stops.
+
+This affects **all** Rails apps using `tailwindcss-rails` v4 with foreman, not
+just IronAdmin.
+
+**Solution:** Edit `Procfile.dev` and append `[always]` to the watch task:
+
+```diff
+  web: bin/rails server
+- css: bin/rails tailwindcss:watch
++ css: bin/rails tailwindcss:watch[always]
 ```
 
-Find the gem path with: `bundle show iron_admin`
+The `always` flag tells the Tailwind binary to keep watching even when stdin is
+closed. This is the recommended workaround until the issue is resolved upstream.
 
 ## Resource Issues
 
@@ -64,7 +93,7 @@ Find the gem path with: `bundle show iron_admin`
 **Cause:** Resource not registered or menu configuration issue.
 
 **Solutions:**
-1. Ensure resource file exists in `app/iron_admin/`
+1. Ensure resource file exists in `app/iron_admin/resources/`
 2. Check resource inherits from `IronAdmin::Resource`
 3. Verify filename matches class name (`user_resource.rb` → `UserResource`)
 

data/lib/generators/iron_admin/install/install_generator.rb

@@ -10,6 +10,7 @@ module IronAdmin
     # - Adds an initializer with default configuration
     # - Creates a sample dashboard
     # - Mounts the engine at /admin in routes
+    # - Adds the Tailwind CSS import for engine styles
     #
     # @example Running the generator
     #   rails generate iron_admin:install
@@ -18,10 +19,11 @@ module IronAdmin
     class InstallGenerator < Rails::Generators::Base
       source_root File.expand_path("templates", __dir__)
 
-      # Creates the directory for resource definitions.
+      # Creates the directory structure for resource and dashboard definitions.
       # @return [void]
-      def create_iron_admin_directory
-        empty_directory "app/iron_admin"
+      def create_iron_admin_directories
+        empty_directory "app/iron_admin/resources"
+        empty_directory "app/iron_admin/dashboards"
       end
 
       # Copies the initializer template with default configuration.
@@ -33,7 +35,7 @@ module IronAdmin
       # Copies the dashboard template.
       # @return [void]
       def copy_dashboard
-        template "dashboard.rb.tt", "app/iron_admin/dashboard.rb"
+        template "dashboard.rb.tt", "app/iron_admin/dashboards/admin_dashboard.rb"
       end
 
       # Adds the engine mount to config/routes.rb.
@@ -41,6 +43,25 @@ module IronAdmin
       def add_route
         route 'mount IronAdmin::Engine => "/admin"'
       end
+
+      # Adds the IronAdmin CSS import to the Tailwind application stylesheet.
+      #
+      # This import is required so the Tailwind compiler scans the engine's
+      # views and components for CSS utility classes. Without it, the admin
+      # panel renders unstyled.
+      #
+      # @return [void]
+      def add_tailwind_import
+        css_path = "app/assets/tailwind/application.css"
+        return unless File.exist?(File.join(destination_root, css_path))
+
+        import_line = '@import "../builds/tailwind/iron_admin";'
+        content = File.read(File.join(destination_root, css_path))
+
+        return if content.include?(import_line)
+
+        append_to_file css_path, "#{import_line}\n"
+      end
     end
   end
 end

data/lib/generators/iron_admin/install/templates/dashboard.rb.tt

@@ -1,2 +1,6 @@
-class AdminDashboard < IronAdmin::Dashboard
+module IronAdmin
+  module Dashboards
+    class AdminDashboard < IronAdmin::Dashboard
+    end
+  end
 end

data/lib/generators/iron_admin/resource/resource_generator.rb

@@ -20,7 +20,7 @@ module IronAdmin
       # Creates the resource file from template.
       # @return [void]
       def create_resource_file
-        template "resource.rb.tt", File.join("app/iron_admin", class_path, "#{file_name}_resource.rb")
+        template "resource.rb.tt", File.join("app/iron_admin/resources", class_path, "#{file_name}_resource.rb")
       end
     end
   end

data/lib/generators/iron_admin/resource/templates/resource.rb.tt

@@ -1,4 +1,8 @@
+module IronAdmin
+  module Resources
 <% module_namespacing do -%>
-class <%= class_name %>Resource < IronAdmin::Resource
-end
+    class <%= class_name %>Resource < IronAdmin::Resource
+    end
 <% end -%>
+  end
+end

data/lib/iron_admin/engine.rb

@@ -38,31 +38,17 @@ module IronAdmin
       config.i18n.load_path += Dir[root.join("config", "locales", "**", "*.yml")]
     end
 
-    initializer "iron_admin.tailwindcss" do
-      if defined?(Tailwindcss)
-        engine_css = root.join("app/assets/tailwind/iron_admin/engine.css")
-
-        Rails.application.config.after_initialize do
-          if defined?(Rake) && Rake::Task.task_defined?("tailwindcss:engines")
-            Rake::Task["tailwindcss:engines"].enhance do
-              tailwind_dir = Rails.root.join("app/assets/tailwind")
-              bridge_file = tailwind_dir.join("iron_admin.css")
-
-              if engine_css.exist? && tailwind_dir.exist?
-                File.write(bridge_file, <<~CSS)
-                  /* DO NOT MODIFY - auto-generated by iron_admin */
-                  @import "#{engine_css}";
-                CSS
-              end
-            end
-          end
-        end
-      end
+    initializer "iron_admin.autoload", before: :set_autoload_paths do
+      resource_path = Rails.root.join("app/iron_admin")
+      Rails.autoloaders.main.push_dir(resource_path, namespace: IronAdmin) if resource_path.exist?
     end
 
-    config.after_initialize do
+    config.to_prepare do
       resource_path = Rails.root.join("app/iron_admin")
-      Rails.autoloaders.main.eager_load_dir(resource_path.to_s) if resource_path.exist?
+      if resource_path.exist?
+        IronAdmin::ResourceRegistry.reset!
+        Rails.autoloaders.main.eager_load_dir(resource_path)
+      end
     end
   end
 end

data/lib/iron_admin/resource.rb

@@ -86,7 +86,7 @@ module IronAdmin
       def model
         return model_class_override if model_class_override
 
-        name.sub(/Resource\z/, "").constantize
+        name.sub(/Resource\z/, "").sub(/\AIronAdmin::Resources::/, "").constantize
       end
 
       # Configures display and behavior options for a field.

data/lib/iron_admin/version.rb

@@ -3,5 +3,5 @@
 module IronAdmin
   # The current version of the IronAdmin gem.
   # @return [String]
-  VERSION = "0.4.1"
+  VERSION = "0.5.0"
 end

data/lib/iron_admin.rb

@@ -25,7 +25,7 @@ require "iron_admin/engine"
 # 1. Add the gem to your Gemfile and run bundle install
 # 2. Run the install generator: `rails generate iron_admin:install`
 # 3. Mount the engine in config/routes.rb: `mount IronAdmin::Engine => "/admin"`
-# 4. Create resources in app/iron_admin/ for each model you want to manage
+# 4. Create resources in app/iron_admin/resources/ for each model you want to manage
 #
 # == Key Concepts
 #
@@ -34,22 +34,30 @@ require "iron_admin/engine"
 # that inherits from {IronAdmin::Resource} and provides a DSL for configuring
 # fields, filters, actions, and authorization.
 #
-#   class UserResource < IronAdmin::Resource
-#     field :email, readonly: true
-#     field :password_digest, visible: false
-#     searchable :name, :email
-#     filter :role, type: :select, options: %w[admin user]
+#   module IronAdmin
+#     module Resources
+#       class UserResource < IronAdmin::Resource
+#         field :email, readonly: true
+#         field :password_digest, visible: false
+#         searchable :name, :email
+#         filter :role, type: :select, options: %w[admin user]
+#       end
+#     end
 #   end
 #
 # === Dashboard
 # The dashboard is the admin panel home page. Create a class inheriting from
 # {IronAdmin::Dashboard} to define metrics, charts, and recent record lists.
 #
-#   class AdminDashboard < IronAdmin::Dashboard
-#     metric :total_users do
-#       User.count
+#   module IronAdmin
+#     module Dashboards
+#       class AdminDashboard < IronAdmin::Dashboard
+#         metric :total_users do
+#           User.count
+#         end
+#         recent :orders, limit: 10
+#       end
 #     end
-#     recent :orders, limit: 10
 #   end
 #
 # === Configuration

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: iron_admin
 version: !ruby/object:Gem::Version
-  version: 0.4.1
+  version: 0.5.0
 platform: ruby
 authors:
 - RubyLab
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-02-14 00:00:00.000000000 Z
+date: 2026-02-17 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: haml-rails