autoprefixer-rails: CSS vendor prefixes in the Rails Asset Pipeline, with ExecJS as the bridge

Vendor prefixes through the Sprockets Asset Pipeline, not through webpack

Vendor-prefix automation in autoprefixer-rails works as a post-processing step in the Rails Asset Pipeline. A developer writes a stylesheet without vendor prefixes, and the gem adds them before the browser sees the file. Autoprefixer, a JavaScript library that reads the Can I Use database, is the underlying tool that decides which prefixes a given property needs for a given set of browsers.

autoprefixer-rails provides the Ruby adapter between that JavaScript library and the Asset Pipeline. It is not a Ruby rewrite of Autoprefixer. The JavaScript runs inside the Ruby process via ExecJS, which means the gem depends on a compatible JavaScript runtime being available wherever CSS compilation happens, whether on a developer's laptop, a CI server or a production build host.

For new projects, webpack or Gulp are the better choices, as the gem's own documentation says directly. Any Rails application that has already adopted webpack for JavaScript can use the Autoprefixer PostCSS plugin there and leave this gem out entirely. Its value is specifically for projects committed to Sprockets and the Asset Pipeline, where introducing a webpack step would cost more than adding one gem.

ExecJS picks the JavaScript runtime, and therubyracer is blocked

ExecJS is the library that runs JavaScript from within a Ruby process. autoprefixer-rails uses it to execute the Autoprefixer code, and the tested runtimes are Node.js version 10 and up and mini_racer. therubyracer is explicitly named as something that will not work.

therubyracer was a common choice for running JavaScript in Rails before Node.js became standard in web development workflows. Projects that still have therubyracer in their Gemfile will find it does not satisfy this requirement; a separate, supported runtime is necessary.

Node.js 10 is the documented lower bound. Any modern Node.js installation will exceed that floor. The more pressing question for many teams is whether Node.js is installed at all in environments that were previously pure Ruby. On a server that has never needed it, installing it is the first setup step.

Windows adds another constraint. On that platform, Node.js must be installed because the gem will not work with the old JScript engine that Windows provides by default. No JScript version is given as acceptable; Node.js or mini_racer is required on every platform, including Windows.

Adding the gem and clearing the cache before the first prefixed output

Adding autoprefixer-rails to a Rails project starts with the Gemfile:

gem "autoprefixer-rails"

After bundling, the Rails cache needs clearing before the Asset Pipeline will apply prefixes:

rake tmp:clear

Clearing the cache is required on first install and after every configuration change, because old compiled assets persist and will continue serving without prefixes until they are removed. A developer who adds a `.browserslistrc` file and skips this step will not see any change in the compiled output.

A first verification can be done with a Sass rule that exercises the prefixing:

:fullscreen a
  display: flex

Compiling those assets and inspecting the output should show 4 separate selectors with WebKit, Mozilla and Microsoft vendor prefixes alongside the unprefixed form. Prefixing happens at compile time, so the browser receives a static file with all variants already written out.

To remove autoprefixer-rails from the Asset Pipeline without removing the gem itself, an uninstall call is available:

AutoprefixerRails.uninstall(Rails.application.assets)

.browserslistrc controls which browsers get prefixes, but geographic queries hit a limit

Autoprefixer reads a Browserslist configuration file to decide which browsers need prefixes for a given CSS property. In autoprefixer-rails, this file can be saved under `app/assets/stylesheets/` or any ancestor directory of that path. The format supports range queries and version selectors:

> 1%
last 2 versions
IE > 8 # comment

One category of query does not work in this integration. The `> 5% in US` syntax, which filters by browser usage within a specific country, requires custom usage statistics that ExecJS cannot supply. Teams whose browser policy depends on country-specific usage data need to move to webpack or Gulp to use those queries.

Changing `.browserslistrc` requires another `rake tmp:clear` before the new configuration takes effect. To inspect what the current configuration will do before recompiling everything, the gem provides a Rake task:

rake autoprefixer:info

This task prints which browsers the current query resolves to and which CSS properties will receive prefixes. Running it before committing a browser configuration change is a cheap way to catch surprises in the compiled output.

Two Autoprefixer features the Rails wrapper cannot support

Autoprefixer supports 2 input mechanisms that autoprefixer-rails cannot provide. The first is reading browser targets from the `browsers` field in `package.json`. The second is supplying custom browser usage statistics to the Can I Use database queries.

Both are blocked by the ExecJS integration layer. The gem runs Autoprefixer in a sandboxed JavaScript environment that does not have access to the project's `package.json` or to external statistics sources. A project that has already configured browser targets in `package.json` will find those settings silently ignored when using this gem; the effective configuration is whatever `.browserslistrc` file is found, or the Autoprefixer defaults if no file exists.

Both are listed as unsupported features in the repository documentation, without qualification. Before adopting the gem, check whether the existing project relies on either mechanism and whether the `.browserslistrc` alternative covers the same browser set. A mismatch means the prefixes the Asset Pipeline generates will differ from what the Autoprefixer configuration in `package.json` intended.

The plain Ruby API and Sprockets integration outside Rails

For non-Rails Ruby applications using Sprockets, the gem supports an explicit install call. Given a Sprockets::Environment object, the integration is:

require "autoprefixer-rails"
AutoprefixerRails.install(assets)

After that call, any CSS passing through the Sprockets environment receives vendor prefixes. This works in Sinatra or any other framework that uses Sprockets for asset compilation, without needing a Rails application object present.

For processing CSS without any asset pipeline, the `process` class method takes a string directly:

prefixed = AutoprefixerRails.process(css, from: 'main.css').css

The `from` option provides the source filename, which matters for source map generation and for error messages that include line numbers. The result object exposes a `.css` method returning the prefixed string. This path suits batch processing of stylesheets outside of Sprockets or any framework, such as in a standalone build script or a content pipeline that already manages its own file loading.

Source maps can span from Sass to the final output with from, to and prev options

autoprefixer-rails generates source maps and can incorporate an existing map from an earlier compilation step. To generate a new map, the `process` call takes `map: true` along with source and destination file paths:

result = AutoprefixerRails.process(css,
    map:   true,
    from: 'main.css',
    to:   'main.out.css')

Both `from` and `to` are required for a correct map. Without them, the tool cannot construct accurate source positions.

When CSS arrives from a Sass compilation that already produced a source map, that map can be passed as the `prev` value inside the `map` option:

result = AutoprefixerRails.process(css, {
    map:   { prev: File.read('main.sass.css.map') },
    from: 'main.sass.css',
    to:   'main.min.css')

result.map #=> Source map from main.sass to main.min.css

The resulting map covers the full chain from the Sass source to the final prefixed CSS, merging the two compilation steps. Ruby-style key naming works throughout, so `sources_content: false` is valid in place of the PostCSS camelCase `sourcesContent`. The complete option set lives in the PostCSS documentation, since AutoprefixerRails converts Ruby naming to JavaScript naming before passing options through.

No tagged releases, a Compass post-compile hook, and the visual cascade toggle

The repository carries no GitHub releases. There is no versioned tag to pin by a release identifier; the gem version can only be tracked through the project's dependency file. The last push was on 2026-10-05, and the repository is not archived. The repository's Dockerfile is based on ruby:2.7, which reflects the build environment for the gem itself rather than a version requirement on the consuming application.

By default, Autoprefixer aligns multiple vendor-prefixed values in a visual column, as shown in this 3-declaration example from the documentation:

a {
  -webkit-box-sizing: border-box;
     -moz-box-sizing: border-box;
          box-sizing: border-box
}

Setting `cascade: false` in `config/autoprefixer.yml` or in the `process()` options turns this off and produces flat output. For teams running automated CSS linters that flag whitespace differences between property lines, the cascade alignment may require a linter exception.

For Compass binary users who cannot migrate to Gulp and need prefix addition after `compass compile`, the repository documents a post-compile hook in `config.rb` that calls `AutoprefixerRails.process` on each saved stylesheet. Installing the gem for that use requires:

gem install autoprefixer-rails

The repository describes this Compass integration as a hack, and the label is accurate: it runs Autoprefixer outside any official integration point and requires the gem installed globally rather than through a Bundler-managed Gemfile.

Editorial conclusion

autoprefixer-rails suits Rails projects committed to the Sprockets Asset Pipeline and not ready to move to webpack or Gulp. It handles common prefix cases: flexbox variants, full-screen selectors and box-sizing. Skip it when the project needs browser targets from package.json or custom usage statistics, since those features do not pass through the ExecJS layer. Skip it if therubyracer is the only JavaScript runtime available. Before adopting, confirm Node.js 10 or newer or mini_racer on every compile machine, run rake autoprefixer:info against the browser configuration, and verify no geographic queries appear in it.

Frequently asked questions

Official sources

1. ai/autoprefixer-rails on GitHub
2. Issues
3. License: MIT
4. Project website
5. README