Awesome
browserslist_useragent gem
<img align="right" width="120" height="120" src="https://cdn.rawgit.com/pastelsky/browserslist-useragent/master/logo.svg" alt="Browserslist Useragent logo (original by Anton Lovchikov)" />
Find if a given user agent string satisfies a Browserslist browsers.
Browserslist is a popular config in many front-end tools like Autoprefixer or Babel. This gem allow you to use this config in Ruby project to check user agent string and, for examplle, show “Your browsers is outdated” warning for user with old browser.
Usage
1. Setup Browserslist
Run in webpack directory to install browserslist
npm package:
npm install --save-dev browserslist
Add the following lines to your webpack config to generate the browsers.json
file during build step:
const browserslist = require('browserslist')
const fs = require('fs')
fs.writeFileSync('./browsers.json', JSON.stringify(browserslist()))
In a Rails/Webpacker environment add the above lines to the top of your app/config/webpack/environment.js
file.
Add browsers.json
file to .gitignore
.
2. Install gem
Add this line to Gemfile
gem 'browserslist_useragent'
Run bundle install
.
3. Add helper
Define new helper in app/helpers/application_helper.rb
:
def supported_browser?
@browsers ||= JSON.parse(File.read(PATH_TO_BROWSERS_JSON))
matcher = BrowserslistUseragent::Match.new(@browsers, request.user_agent)
matcher.browser? && matcher.version?(allow_higher: true)
end
4. Use helper in template
Put a warning message for users with an unsupported browser in app/views/layouts/_unsupported_browser_warning
and add this check in application layout:
body
- if !supported_browser?
render 'layouts/unsupported_browser_warning'
Separated projects
If you have separated projects for Ruby backend and Node.js frontend, you will prefer to get browsers.json
over HTTP.
fs.writeFileSync(
path.join(__dirname, 'public', 'browsers.json'),
JSON.stringify(browserslist(undefined, { path: path.join(__dirname, '..') }))
)
Gets browserslist.json
over HTTP (with caching) once (per web application instance) and use it to match user agent for every request:
# caches http response locally with etag
http_client = Faraday.new do |builder|
builder.use Faraday::HttpCache, store: Rails.cache
builder.adapter Faraday.default_adapter
end
@browsers = JSON.parse(
http_client.get(FRONTEND_HOST + '/browsers.json').body
)
API
BrowserslistUseragent::Match
is the main class performing matching user agent string to browserslist.
It provides 2 methods:
version?(allow_higher: false)
- determines matching browser and it's versionbrowser?
- determines matching only browser family
require 'browserslist_useragent'
matcher = BrowserslistUseragent::Match.new(
['Firefox 53'],
'Mozilla/5.0 (Windows NT 10.0; rv:54.0) Gecko/20100101 Firefox/53.0'
)
matcher.browser? # returns true
matcher.version? # return true
matcher = BrowserslistUseragent::Match.new(
['Firefox 54'],
'Mozilla/5.0 (Windows NT 10.0; rv:54.0) Gecko/20100101 Firefox/53.0'
)
matcher.browser? # returns true
matcher.version? # return false
Supported browsers
Chrome, Firefox, Safari, IE, Edge
PRs to add more browserslist supported browsers are welcome 👋
Notes
- All browsers on iOS (Chrome, Firefox etc) use Safari's WebKit as the underlying engine, and hence will be resolved to Safari. Since
browserslist
is usually used for transpiling / autoprefixing for browsers, this behaviour is what's intended in most cases, but might surprise you otherwise. - Right now, Chrome for Android and Firefox for Android are resolved to their desktop equivalents. The
caniuse
database does not currently store historical data for these browsers separately (except the last version) See #156
Development (with Docker))))
After checking out the repo, run:
docker-compose run app bundle install
Run tests with:
docker-compose run app bundle exec rspec
Run RuboCop with:
docker-compose run app bundle exec rubocop
Contributing
Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/browserslist-useragent-ruby.
License
The gem is available as open source under the terms of the MIT License.