v4: support running ActiveAdmin from a Rails engine and adding JavaScript to its pages #9147

Problem

ActiveAdmin 4 assumes the host application owns both its import map and its routes. An app that keeps its admin in a Rails engine, and any plugin that ships its own JavaScript, has to work around that with undocumented patches, such as the ones in #8346. The patches break silently when ActiveAdmin changes its internals.

This blocks active_admin_theme 4, which ships ES modules that must load on every ActiveAdmin page. It also affects every other ActiveAdmin 4 plugin with JavaScript, and every app that runs ActiveAdmin from an engine.

The goal is one documented way to add modules to ActiveAdmin pages from the host app and from an engine, and to mount ActiveAdmin's routes in an engine without patches.

What apps and plugins patch today

Line numbers are from 4.0.0.beta23. The workarounds come from active_admin_theme and from an app that runs ActiveAdmin from a non-isolated engine.

Recommended engine recipe

An engine that adds JavaScript to ActiveAdmin pages works today with no patch to ActiveAdmin internals:

initializer "my_engine.importmap", after: "active_admin.importmap" do |app|
  next unless app.config.respond_to?(:importmap)

  ActiveAdmin.importmap.draw(root.join("config/importmap.rb"))
  app.config.assets.paths << root.join("app/javascript")
end

Two gaps remain: the engine cannot add its directory to the cache sweeper, and it still needs the module registry or an _html_head override to import its entry module. The changes above close both.

Documentation to add

UPGRADING.md says ActiveAdmin 4 assumes importmap-rails, but no page says that ActiveAdmin pages use a separate import map. Add a "JavaScript" section that covers these cases:

• In the host app: pin a module into ActiveAdmin.importmap from an initializer, and register it to be imported.
• In an engine: the initializer above, with after: "active_admin.importmap".
• Sharing the host map: the trade-off, and the setting that selects it.
• Arbre components defined in an engine or a gem: builder_method runs when the class body loads, so the component file must load before any ActiveAdmin.register block. Today each project picks its own require or eager_load_dir hook. Document one.

Suggested pull requests

1. The JavaScript documentation section. It needs no code.
2. config.importmap_watches.
3. Route helpers from the route set passed to ActiveAdmin.routes.
4. The config.importmap setting, if the maintainers want to support a shared map.

The module registry is item 1 of the layout proposal (#9146). Would you accept these? Items 3 and 4 change behavior, so I'd like your view before writing them.

Related: a failed destroy hides the reason

The same app also patches destroy. When destroy returns false, as with a before_destroy that throws :abort or dependent: :restrict_with_error, the flash says only "Widget could not be destroyed." and drops resource.errors. A dependent: :restrict_with_exception association raises ActiveRecord::DeleteRestrictionError from destroy_resource (app/controllers/active_admin/resource_controller/data_access.rb:195), which nothing rescues, so the request fails with a 500 error.

#5369 was closed as not planned in 2023. Would a small pull request that appends resource.errors.full_messages to the alert and rescues the restriction error be welcome now?