Browserslist
Library to share supported browsers list between different front-end tools,
like Autoprefixer, Stylelint and babel-env-preset.
In package.json
:
{
"private": true,
"dependencies": {
"autoprefixer": "^6.5.4"
},
"browserslist": [
"> 1%",
"last 2 versions"
]
}
Or in browserslist
config:
> 1%
Last 2 versions
IE 10
Developers set browsers list in queries like last 2 version
to be free from updating browser versions manually.
Browserslist will use Can i Use data for this queries.
Browserslist will take browsers queries from tool option,
browserslist
config, browserslist
section in package.json
or environment variables.
You can test Browserslist queries in online demo.
Queries
Browserslist will use browsers query from one of this sources:
- Tool options. For example
browsers
option in Autoprefixer. BROWSERSLIST
environment variable.browserslist
config file in current or parent directories.browserslist
key in package.json
file in current or parent directories.- If the above methods did not produce a valid result
Browserslist will use defaults:
> 1%, last 2 versions, Firefox ESR
.
We recommends to write queries in browserslist
config or package.json
.
You can specify the versions by queries (case insensitive):
last 2 versions
: the last 2 versions for each major browser.last 2 Chrome versions
: the last 2 versions of Chrome browser.> 5%
: versions selected by global usage statistics.> 5% in US
: uses USA usage statistics. It accepts two-letter country code.> 5% in my stats
: uses custom usage data.ie 6-8
: selects an inclusive range of versions.Firefox > 20
: versions of Firefox newer than 20.Firefox >= 20
: versions of Firefox newer than or equal to 20.Firefox < 20
: versions of Firefox less than 20.Firefox <= 20
: versions of Firefox less than or equal to 20.Firefox ESR
: the latest [Firefox ESR] version.iOS 7
: the iOS browser version 7 directly.not ie <= 8
: exclude browsers selected before by previous queries.
You can add not
to any query.
Browserslist works with separated versions of browsers.
You should avoid queries like Firefox > 0
.
Multiple criteria are combined as a boolean OR
. A browser version must match
at least one of the criteria to be selected.
All queries are based on the Can I Use support table,
e.g. last 3 iOS versions
might select 8.4, 9.2, 9.3
(mixed major and minor),
whereas last 3 Chrome versions
might select 50, 49, 48
(major only).
Browsers
Names are case insensitive:
Major Browsers
Chrome
for Google Chrome.Firefox
or ff
for Mozilla Firefox.Explorer
or ie
for Internet Explorer.Edge
for Microsoft Edge.iOS
or ios_saf
for iOS Safari.Opera
for Opera.Safari
for desktop Safari.ExplorerMobile
or ie_mob
for Internet Explorer Mobile.
Others
Android
for Android WebView.BlackBerry
or bb
for Blackberry browser.ChromeAndroid
or and_chr
for Chrome for Android
(in Other section, because mostly same as common Chrome
).FirefoxAndroid
or and_ff
for Firefox for Android.OperaMobile
or op_mob
for Opera Mobile.OperaMini
or op_mini
for Opera Mini.Samsung
for Samsung Internet.UCAndroid
or and_uc
for UC Browser for Android.
Config File
Browserslist config should be named browserslist
and have browsers queries
split by a new line. Comments starts with #
symbol:
> 1%
Last 2 versions
IE 8
Browserslist will check config in every directory in path
.
So, if tool process app/styles/main.css
, you can put config to root,
app/
or app/styles
.
You can specify direct path in BROWSERSLIST_CONFIG
environment variables.
package.json
If you want to reduce config files in project root, you can specify
browsers in package.json
with browserslist
key:
{
"private": true,
"dependencies": {
"autoprefixer": "^6.5.4"
},
"browserslist": [
"> 1%",
"last 2 versions"
]
}
Environments
You can also specify different browser queries for various environments.
Browserslist will choose query according to BROWSERSLIST_ENV
or NODE_ENV
variables. If none of them is declared, Browserslist will firstly look
for development
queries and then use defaults.
In package.json
:
{
…
"browserslist": {
"production": [
"last 2 version",
"ie 9"
],
"development": [
"last 1 version"
]
}
}
In browserslist
config:
[production]
last 2 version
ie 9
[development]
last 1 version
Environment Variables
If some tool use Browserslist inside, you can change browsers settings
by environment variables:
-
BROWSERSLIST
with browsers queries.
BROWSERSLIST="> 5%" gulp css
-
BROWSERSLIST_CONFIG
with path to config file.
BROWSERSLIST_CONFIG=./config/browserslist gulp css
-
BROWSERSLIST_ENV
with environments string.
BROWSERSLIST_ENV="development" gulp css
-
BROWSERSLIST_STATS
with path to the custom usage data
for > 1% in my stats
query.
BROWSERSLIST_STATS=./config/usage_data.json gulp css
Custom Usage Data
If you have a website, you can query against the usage statistics of your site:
-
Import your Google Analytics data into Can I Use.
Press Import…
button in Settings page.
-
Open browser DevTools on Can I Use and paste this snippet
into the browser console:
var e=document.createElement('a');e.setAttribute('href', 'data:text/plain;charset=utf-8,'+encodeURIComponent(JSON.stringify(JSON.parse(localStorage['usage-data-by-id'])[localStorage['config-primary_usage']])));e.setAttribute('download','stats.json');document.body.appendChild(e);e.click();document.body.removeChild(e);
-
Save the data to a browserslist-stats.json
file in your project.
Of course, you can generate usage statistics file by any other method.
File format should be like:
{
"ie": {
"6": 0.01,
"7": 0.4,
"8": 1.5
},
"chrome": {
…
},
…
}
Note that you can query against your custom usage data
while also querying against global or regional data.
For example, the query > 1% in my stats, > 5% in US, 10%
is permitted.
JS API
var browserslist = require('browserslist');
var process = function (source, opts) {
var browsers = browserslist(opts.browsers, {
stats: opts.stats,
path: opts.file,
env: opts.env
});
}
Queries can be a string "> 5%, last 1 version"
or an array ['> 5%', 'last 1 version']
.
If a query is missing, Browserslist will look for a config file.
You can provide a path
option (that can be a file) to find the config file
relatively to it.
For non-JS environment and debug purpose you can use CLI tool:
browserslist "> 1%, last 2 versions"
Coverage
You can get total users coverage for selected browsers by JS API:
browserslist.coverage(browserslist('> 1%'))
browserslist.coverage(browserslist('> 1% in US'), 'US')
Or by CLI:
$ browserslist --coverage "> 1%"
These browsers account for 81.4% of all users globally
$ browserslist --coverage=US "> 1% in US"
These browsers account for 83.1% of all users in the US