ActionVersionPreview

Preview multiple versions of a Rails UI in separate browser tabs using native view variants. Add variant templates, open their URLs, and compare designs while signed in as the same user. No additional database, feature-flag service, or JavaScript is required.

Full usage guide · Changelog · RubyGems

Add the gem to your Rails application's Gemfile:

gem "action_version_preview", "~> 0.2.0"

Run bundle install and restart the application. No generator or engine mount is needed. Preview selection is added to controllers inheriting from ActionController::Base.

For a DashboardController#show action, keep a default template and add variants:

app/views/dashboard/show.html.erb
app/views/dashboard/show.html+v2.erb
app/views/dashboard/show.html+redesign.erb

Use names such as v2, redesign, or new_layout for automatic switcher discovery.

In development or test:

The last example keeps any variant your application already set, such as a mobile variant. Otherwise it renders the default template.

Put this near the end of your application layout's body:

<%= variant_switcher %>

The switcher appears only when preview mode is requested, access is allowed, and variant templates are discovered for the current action. Its links preserve the current path, mounted prefix, and query filters. Default removes the preview parameter and closes the switcher. Add ?vv=true again to reopen it.

Automatic discovery in 0.2.0 covers HTML ERB action templates in the host app's app/views/<controller_path> directory. See the discovery limits for layouts, partials, other handlers, and engine views.

By default, previews are enabled only in development and test. Production, staging, and other environments deny preview selection until you configure access.

# config/initializers/action_version_preview.rb
ActionVersionPreview.configure do |config|
  config.param_name = :vv # Optional; a string also works.
  config.access_check = ->(controller) {
    Rails.env.development? || Rails.env.test? ||
      (controller.respond_to?(:current_user, true) &&
        controller.send(:current_user)&.admin?)
  }
end

Adapt current_user and admin? to your authentication system. The example also works when current_user is private. Your user/context must be available when the preview callback runs; see access control and callback order.

The preview parameter applies to one request. Links and redirects elsewhere in your app do not inherit it automatically. Ordinary application authorization still controls access to data and actions.

• Fixes ActionVersionPreview::SwitcherHelper load-order errors during application boot and asset precompilation, including early controller/view loading.
• Keeps switcher links on the current request path. Query keys such as host and protocol remain query data; POST body fields are not copied into URLs.
• Adds boot, reload, packaged-gem precompilation, and switcher URL regression tests.

To upgrade from 0.1.0, update your Gemfile constraint if necessary, run bundle update action_version_preview, and rebuild/restart the application. No migration or configuration change is required. Read the 0.2.0 release notes.

• Declared requirements: Ruby 3.1+, Rails 7.0 or later, below 9.0.
• Each Rails version may require a newer Ruby; the reviewed Rails 8.1 bundle requires Ruby 3.2+.
• Release validation used Ruby 4.0.5 with Rails 8.1.3.1. CI is configured for Ruby 3.4.7. A full matrix of the declared versions is not yet in place.
• Automatic controller integration targets ActionController::Base, not API-only controllers inheriting directly from ActionController::API.

bundle install
bin/rails test
bin/rubocop
RAILS_ENV=test bundle exec rake app:zeitwerk:check
bundle exec rake build

The test suite includes an isolated host that installs the built gem and compiles assets in production mode. See the release procedure for security scans and publication.

Why I built design previews for Rails

MIT License.