Changelog
All notable changes to this project are documented here. The format follows Keep a Changelog, and the project aims to follow Semantic Versioning from 1.0.
Unreleased
Changed
- Custom actions in the contract.
core.yamldeclares GET member actions (runMemberActionGet, answeringActionGetResponse: a form, page content, options or a redirect's result), lets action writes answerActionWriteResponse(a result or a re-rendered form), and declares their501 unsupported. The OpenAPI document gives member, collection and page actions the same responses.
Fixed
- The client's files (
ui.asset_prefix) are answered by a Rack middleware placed before the cookie and session middleware. They were served from the router, behind the session, so a host whose stack loads the session sentSet-Cookieon public, immutable responses, which a CDN could cache and hand to other visitors. Files that aren't hashed now sayCache-Control: no-cachethemselves instead of relying on later middleware.
0.2.0
Added
- MCP agent workflow tools.
count_recordsreturns the total and per-scope counts for filters and a scope, through the index's own guards, with no rows.update_recordtakesdry_run: trueand returns each field'sfromandtowithout saving; it is the API'sPATCH ... dry_run, validated inside a rolled-back transaction, with masked values hidden and nowriteaudit event. It previews only plain attributes the form offers a control for, and in-memory nested rows, anddry_runis refused anywhere but update.prompts/listandprompts/getserve three runbooks (find_record,review_recent_changes,bulk_update), offered only when the token can use the tools they name, andinitializeadvertises thepromptscapability. - A project website on GitHub Pages (
apps/site, VitePress): a landing page, the guides and the changelog, plus a demo of the React admin that runs on mock data (pnpm --filter standalone build:demo). - The crawl runs against a host app:
--base-urltakes a host's admin URL,--authnames a login hook, and thereactiveadmin-crawlbin runs it from a checkout. Docs warn that crawling real data creates audit reads and recommend a dedicated user. - Performance budgets for the crawl (
--budget=p95=1500,--budget=index.max=4000,--budget-file): the run exits non-zero and the report lists the screens over the limit. --paritycompares each index's first page (row count and record ids, never values) with classic ActiveAdmin. Table rows, cards and grid items carrydata-row-id.- Keyboard navigation on index pages:
j/kor the arrow keys move a visible row cursor in the table, card and grid views,Enteropens the row,xselects it when the resource has batch actions, and/focuses the filters. Press?for a dialog listing the shortcuts on the current screen. - The gem ships a prebuilt React client (
gem/vendor/client, built byrake package), so installing it from RubyGems needs no repository checkout and no Node.js. It is stamped with the gem version and manifestschema_version, and served only while they match. Builds refer to their own files relatively, so the packaged client works under anyui.asset_prefixor CDN, andRA_ASSET_PREFIXis gone.config.ui.client_assetsand a host's own build (rake reactiveadmin:client:build) both win over it. - A
packaged gemCI job that builds the gem, installs it from a local index and smoke-tests the manifest and the client page. - A
releaseworkflow: pushing av<version>tag builds the gem with the client, smoke-tests it, publishes it to RubyGems with trusted publishing after maintainer approval, and creates a GitHub release from the CHANGELOG. The gem now includes the README, LICENSE and CHANGELOG, and lists Form Health as its author. rails generate reactiveadmin:install, which asks how to start (guided by default:config.expose = :listedwith a generatedapp/admin/menu.rblisting every registration to prune, and an initializer annotated withTODO(setup)notes; quick:expose :all; strict: only what's listed, plus the dashboard and anything markedreactive { expose true }), which attributes to mask (proposed fromdb/schema.rb), whether to turn on MCP, and who may switch to the new admin, adding the switch to the dashboard. Every answer is also a flag (--preset,--mask,--mcp,--ui,--yes). It mounts the routes, serves ActiveAdmin's namespace, boots the app to check the setup, and changes nothing when run again.- Typed react-query hooks per resource (
useListAuthors) generated from a host's ownrake reactiveadmin:openapidocument withreactiveadmin-gen, through the client'sapiFetch, optionally split by tag. CI generates and typechecks them against the dummy app. - Rollout telemetry: the client reports caught crashes, names only, to
POST {mount}/admin/_client_errors(aclient_error.reactiveadminevent andconfig.error_reporter, in theclient_errorrate-limit bucket), whichconfig.ui.client_errors = falseturns off, andrake reactiveadmin:readinesscombines each resource's doctor mode with recentdegradedand client error counts (config.event_counts) as a checklist for leaving classic. rake reactiveadmin:fixturesrecords scrubbed JSON fixtures of the manifest, meta, index, show and form payloads from a running app, andfixtureHandlersturns them into MSW handlers for Storybook.- A statement that the client needs React 19.2 or later. A React 18 install fails because React Router 8 and the client use React 19 APIs.
- A unified audit envelope: every audit event is also published as
audit.reactiveadminwith one schema (kind, user, resource, action, record ids, channel, client id, request id, correlation id, outcome, time, details), andReactiveAdmin.on_audit { |event| ... }subscribes to it. The existing events are unchanged. - MCP writes carry the tool call's
correlation_id,channel: "mcp"and the token'sclient_idin the envelope. - Batch-action write events carry the selected ids as
record_ids. config.audit_views(defaultfalse) publishes aviewenvelope for API show and edit reads.- Switching between the classic and new admin publishes a
ui_switchenvelope. - Panels'
header_action(the method form) records as typedheader_actions, kept through form content and MCP. - Grid, blog and block index views show a selection checkbox per record when the resource has batch actions.
ReactiveAdmin::RSpec.contract_examples(require "reactive_admin/rspec") runs each registration's meta, index and show against the contract in a host's own suite.
Changed
- The minimum Rails version is now 8.1.
- The middleware serves the client's page only once
config.ui.availablenames who may use it. Until then, upgrading changes nothing, even though a client is now installed.
Security
These close gaps in the API and change what some clients get. Review them before you upgrade.
- Disabled nested fields. A write drops the params of a has_many row's disabled fields, as it already did for top-level fields. A row is held to the saved row its
idnames, or to a new row's fields, whatever index the client sent it at. - Mutating GET actions. GET and HEAD actions stay reads. Declare a GET action that changes data with
reactive { unsafe_gets :name }: it then needs the write scope, is write-audited, is refused byapi :read_only, and needs MCP confirmation inrun_action. - MCP is read-only by default (behavior change). Each resource and page has an MCP mode:
config.mcp.default(new,:read_only) orreactive { mcp :full | :read_only | :none }, withmcp actions: [...]to let agents run named custom or batch actions on a read-only resource. Agents losecreate_record,update_record,delete_record,get_formand everyrun_actionbut GET and HEAD actions not listed inunsafe_getson any resource that doesn't opt in, whatever the token's scopes; addmcp :fullwhere agents must write, or setconfig.mcp.default = :fullfor the old behavior.:noneleaves a resource out of MCP.tools/listhides tools no resource offers, a tool called on a resource whose mode excludes it fails as an unknown resource, and the API refuses MCP-dispatched requests the mode excludes. A mode never widens anapiguard.rake reactiveadmin:doctoradds an "MCP surface" section and warns (mcp_full_sensitive) about:fullon sensitive or masked resources. - MCP.
tools/callanswers a tool the token's scopes hide as an unknown tool.run_actionruns only the member, collection and batch actions the resource declares, and uses a method the action declares rather than the one the caller asks for. - Frames. A frame form or
data-methodlink that isn't a GET is sent, with the session's CSRF token, only to an admin page; anything else is refused, including paths with encoded separators (also inherited from the page URL) or control characters. - CSV exports without a
csvblock. An API export of such a resource takes the attribute columns of itsindexblock, or the secure default columns when it has no table index, instead of ActiveAdmin's id and every content column. Columns that an index block computes are no longer exported. The secure default columns leave out encrypted, filtered, masked and binary columns; columns an index block names are the host's choice and aren't filtered, and masked values are exported raw whenmask_csvis off. Understrict_defaultssuch an export answers422unless a table index block supplies the columns. The table index decides the columns whateverasview is requested. Classic exports keep their columns. Declare acsvblock to choose the columns. - With
mask_csvon, a masked key nested inside a json column is masked in any export, classic included. - The CSV formula escaping flag is per request, so concurrent classic and API exports no longer share it.
- Filter options and conditions. The options of a filter on a plain column list only values from rows the user may read. A filter hidden by
if:orunless:answers404for its options, and the API refuses itsqkeys with400. Option cache keys include the user id. A boundeddistinctscope that doesn't project the column or its primary key offers no options.
Fixed
- Filter and form option lists that read request params (such as other filters' values) are no longer served from the option cache across different params.
- A native view whose API answers 501 reopens in the frame or iframe the action allows, keeping its dialog or sheet and its query, instead of failing.
- A sort picked in the table view is checked against the table's columns when another index view is shown.
openapi/core.yamlships in the gem; the OpenAPI document failed to build from an installed gem without it.config.mount_pathis normalized: a trailing slash ("/api/") or a root mount ("") no longer breaks prefix checks such as contract lookup and CSV export detection.- Switching resources no longer shows the previous resource's rows while the next index loads.
- A scope group's label isn't announced twice by screen readers.
0.1.0
First public release. The gem and the client are early: interfaces may change before 1.0.
Added
- A JSON API (
application/vnd.reactiveadmin+json) served through your ActiveAdmin controllers, so filtering, scoping, sorting, pagination, authentication, authorization and the write path match the classic pages. - Typed manifests, index, show and form payloads: Arbre component trees become typed nodes, Formtastic forms become typed form schemas (including
has_manynested rows), and views that can't be represented natively fall back to sanitized HTML or an embedded classic page. - A generated OpenAPI 3.1 document, filtered to what the requesting admin may access.
- An MCP server (
{mount}/_mcp) whose tools call the same API, with bearer-token authentication and read and write scopes. - A registration DSL (
reactive do ... end) for option sources, masking, query params and API guards, and a menu overlay DSL. - Security controls: explicit exposure (
config.expose = :listed), API guards (api false,:deny,:read_only,:session_only, custom guards), attribute masking, summarized and tokenized JSON values, rate limits, optimistic locking for edits, and audit notifications that carry ids and no record data. - Marking a resource as sensitive (
config.sensitive_resources,reactive { sensitive true }) so that typeahead, option and label lookups that return its records publish alookup.reactiveadminevent. rake reactiveadmin:doctor,reactiveadmin:legacyandreactiveadmin:stylesto measure how much of an admin renders natively and what still depends on classic ActiveAdmin.- A React client (Vite, TypeScript, Tailwind CSS, shadcn/ui, TanStack Table, React Query, orval) with filter bars, scope tabs, batch and member actions, typeahead and date controls, a JSON editor, a command menu, light and dark themes, and Storybook stories checked with axe.
- Serving the client at the classic admin's URLs, chosen per person by a cookie (
config.ui,reactiveadmin_ui_toggle,rake reactiveadmin:client:build). - An end-to-end crawl (
pnpm crawl,pnpm crawl:dummy) that visits every screen the manifest describes. - CI for the gem (Standard Ruby, an RSpec matrix over the default, custom and Pundit authorization adapters on SQLite and PostgreSQL) and for the client (contract drift, types, lint, tests, builds, Storybook, accessibility, crawl).
Naming
The sensitive-data feature was named after one kind of sensitive data during development. It is now generic, and there is no alias for the old names:
config.phi_resourcesis nowconfig.sensitive_resources.reactive { phi true }andreactive { phi false }are nowreactive { sensitive true }andreactive { sensitive false }.- The
phioption stored in a registration'sreactive_optionsis nowsensitive. - The internal
ReactiveAdmin::LookupAudit.phi?is nowsensitive?. - The OpenAPI descriptions of the JSON value endpoint now say that it is audited as a sensitive-data view. The
lookup.reactiveadminnotification and its payload are unchanged.