Browserslist Ruby

Bring browserslist to Ruby.

Since Rails 8.0, you can use allowed browsers to block access to your application for specific browsers. This gem allows you to integrate your existing Browserlist configuration into Rails.

allow_browser versions: Browserslist.browsers

Installation

Add browserslist to your Gemfile:

bundle add browserslist

Usage

Generating a Browserslist

browserslist-rb reads from a .browserslist.json file that must be generated upfront or at build time. This gem ships with a generator that requires npm/npx to be installed. If you generate the file upfront you must make sure it's available at runtime.

# Generate default .browserslist.json file
bundle exec browserslist generate

Build-Time Generation

For Rails applications using modern bundlers, you can generate the browserslist file at build time, depending on your tooling.

Asset Precompilation

You may use the built-in rake task to hook into your asset precompilation process. First require the Rake tasks, then enhance your asset precompilation. Add this to your lib/tasks/assets.rake:

require 'browserslist/rake'

Rake::Task['assets:precompile'].enhance(['browserslist:update'])

Vite Ruby

Add to vite.config.ts using a plugin:

import { defineConfig } from 'vite'
import { execSync } from 'child_process'

export default defineConfig({
  plugins: [
    {
      name: 'browserslist-generator',
      configResolved() {
        execSync('npx browserslist --json > .browserslist.json')
      }
    }
  ]
})

esbuild

Use a build plugin in your esbuild configuration:

require('esbuild').build({
  plugins: [{
    name: 'browserslist-generator',
    setup(build) {
      build.onStart(() => {
        const browserslist = require('browserslist')
        const fs = require('fs')
        fs.writeFileSync('./.browserslist.json', JSON.stringify(browserslist()))
      })
    }
  }]
})

Using the API

Once you have generated your browserslist file, the gem provides a hash of minimum required browser versions:

Browserslist.browsers
# => {chrome: 119.0, firefox: 128.0, edge: 138.0, safari: 18.4, opera: 80.0, ie: false}

For example with Rails 8.0+ allowed browsers:

allow_browser versions: Browserslist.browsers

You may preview the resulting hash using

bundle exec browserslist browsers
# => {chrome: 119.0, firefox: 128.0, edge: 138.0, safari: 18.4, opera: 80.0, ie: false}

Configuration

Configure the gem like so:

Browserslist.configure do |config|
  # Set custom file path 
  config.file_path = ".browserslist.json"
  
  # Enable/disable strict mode 
  # When strict mode is enabled, missing browsers hash value will be set to false, which in conjunction with `allow_browser` means they will be forbidden from accessing your application.
  config.strict = true
end

Browser Support

The gem supports these browsers:

• Chrome (chrome, and_chr)
• Firefox (firefox, and_ff)
• Safari (safari, ios_saf)
• Edge (edge)
• Opera (opera, op_mob)
• Internet Explorer (ie)

Development

After checking out the repo, run bin/setup to install dependencies. Then, run rake test to run the tests. You can also run bin/console for an interactive prompt.

To install this gem onto your local machine, run bundle exec rake install.

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/hschne/browserslist-rb.

License

The gem is available as open source under the terms of the MIT License.