activeadmin-quill_editor/docs/activeadmin-tailwind-4.md

ActiveAdmin + Tailwind CSS v4 Guide

This guide consolidates the ActiveAdmin 4.0.0.beta20 upgrade notes with a working Tailwind v4 build setup. Use it as a template when updating other ActiveAdmin extension gems.

What Changed in ActiveAdmin 4.0.0.beta20 (from UPGRADING.md)

Version Requirements

• Rails 7.2+ (Rails 7.0 and 7.1 are no longer supported)
• Ruby 3.2+ (Ruby 3.0 and 3.1 are no longer supported)

Template Updates

• _site_header.html.erb container class changed from sticky to fixed.
• active_admin.html.erb now includes the pt-16 utility class.

Tailwind v4 Updates

Replace the old Tailwind directives with the new v4 import and config:

-@tailwind base;
-@tailwind components;
-@tailwind utilities;
+@import "tailwindcss";
+
+@config "../../../tailwind-active_admin.config.mjs";

Update your CSS build command:

-"build:css": "tailwindcss -i ./app/assets/stylesheets/active_admin.css -o ./app/assets/builds/active_admin.css --minify -c tailwind-active_admin.config.js"
+"build:css": "npx @tailwindcss/cli -i ./app/assets/stylesheets/active_admin.css -o ./app/assets/builds/active_admin.css --minify"

If you use tailwindcss-rails, prefer the bundled bin/tailwindcss and the @config directive instead of passing -c.

ESM Config Warning

Tailwind config now uses ESM. To avoid the warning:

• Rename tailwind-active_admin.config.js to tailwind-active_admin.config.mjs, or
• Add "type": "module" to package.json.

Breaking Changes Summary

• jQuery and jQuery UI removed.
• columns component removed (use Tailwind grid).
• tabs component removed.
• Replace default_main_content with render "show_default".
• Replace as: :datepicker with as: :date_picker.
• Replace active_admin_comments with active_admin_comments_for(resource).
• Replace attributes_table with attributes_table_for(resource) in sidebars.
• Removed IndexAsBlog, IndexAsBlock, IndexAsGrid.
• Batch action form DSL replaced with partial support.
• Deeply nested submenus removed (only one level supported).
• Removed Panel#header_action and index_column.

New in beta20

• Parent menu item linking support
• Improved comments pagination styling
• Better vertical spacing for has-many forms
• Pointer cursor restored on eligible buttons
• Various accessibility improvements

Recommended Build Setup (tailwindcss-rails)

1. Gemfile

gem "activeadmin", "4.0.0.beta20"
gem "tailwindcss-rails", "~> 4.4.0"

2. Tailwind Input

/* app/assets/stylesheets/active_admin.tailwind.css */
@import "tailwindcss";
@config "../../../tailwind-active_admin.config.mjs";

3. Tailwind Config

// tailwind-active_admin.config.mjs
import { execSync } from "child_process";
import activeAdminPlugin from "@activeadmin/activeadmin/plugin";

const activeAdminPath = execSync("bundle show activeadmin", {
  encoding: "utf-8"
}).trim();

export default {
  content: [
    `${activeAdminPath}/vendor/javascript/flowbite.js`,
    `${activeAdminPath}/plugin.js`,
    `${activeAdminPath}/app/views/**/*.{arb,erb,html,rb}`,
    "./app/admin/**/*.{arb,erb,html,rb}",
    "./app/views/active_admin/**/*.{arb,erb,html,rb}`,
    "./app/views/admin/**/*.{arb,erb,html,rb}`,
    "./app/views/layouts/active_admin*.{erb,html}`,
    "./app/javascript/**/*.js"
  ],
  darkMode: "selector",
  plugins: [activeAdminPlugin]
};

4. Build Tasks

# lib/tasks/active_admin.rake
namespace :active_admin do
  desc "Build Active Admin Tailwind stylesheets"
  task build: :environment do
    command = [
      Rails.root.join("bin/tailwindcss").to_s,
      "-i", Rails.root.join("app/assets/stylesheets/active_admin.tailwind.css").to_s,
      "-o", Rails.root.join("app/assets/builds/active_admin.css").to_s,
      "-m"
    ]

    system(*command, exception: true)
  end
end

5. Tailwind CLI Binstub

bundle binstubs tailwindcss-ruby --force

Notes for Extension Gems

When updating other ActiveAdmin extension gems:

• Keep all JS/CSS inside the gem or npm package; do not copy large files into host apps.
• Add only a thin import to the host app (import "your_gem").
• Use Tailwind v4 @import + @config and ESM config files.
• Avoid jQuery-based plugins or require them explicitly.