1 | # browserslist-useragent-regexp
|
2 |
|
3 | [![ESM-only package][package]][package-url]
|
4 | [![NPM version][npm]][npm-url]
|
5 | [![Node version][node]][node-url]
|
6 | [![Dependencies status][deps]][deps-url]
|
7 | [![Install size][size]][size-url]
|
8 | [![Build status][build]][build-url]
|
9 | [![Coverage status][coverage]][coverage-url]
|
10 | [![Documentation badge][documentation]][documentation-url]
|
11 |
|
12 | [package]: https://img.shields.io/badge/package-ESM--only-ffe536.svg
|
13 | [package-url]: https://nodejs.org/api/esm.html
|
14 |
|
15 | [npm]: https://img.shields.io/npm/v/browserslist-useragent-regexp.svg
|
16 | [npm-url]: https://npmjs.com/package/browserslist-useragent-regexp
|
17 |
|
18 | [node]: https://img.shields.io/node/v/browserslist-useragent-regexp.svg
|
19 | [node-url]: https://nodejs.org
|
20 |
|
21 | [deps]: https://img.shields.io/librariesio/release/npm/browserslist-useragent-regexp
|
22 | [deps-url]: https://libraries.io/npm/browserslist-useragent-regexp/tree
|
23 |
|
24 | [size]: https://packagephobia.com/badge?p=browserslist-useragent-regexp
|
25 | [size-url]: https://packagephobia.com/result?p=browserslist-useragent-regexp
|
26 |
|
27 | [build]: https://img.shields.io/github/actions/workflow/status/browserslist/browserslist-useragent-regexp/tests.yml?branch=master
|
28 | [build-url]: https://github.com/browserslist/browserslist-useragent-regexp/actions
|
29 |
|
30 | [coverage]: https://img.shields.io/codecov/c/github/browserslist/browserslist-useragent-regexp.svg
|
31 | [coverage-url]: https://app.codecov.io/gh/browserslist/browserslist-useragent-regexp
|
32 |
|
33 | [documentation]: https://img.shields.io/badge/API-Documentation-2b7489.svg
|
34 | [documentation-url]: https://browserslist.github.io/browserslist-useragent-regexp
|
35 |
|
36 | A utility to compile [browserslist query](https://github.com/browserslist/browserslist#queries) to a regex to test browser useragent. Simplest example: you can detect supported browsers on client-side.
|
37 |
|
38 | 1) Create `.browserslistrc` config, for example like this:
|
39 |
|
40 | ```
|
41 | last 2 versions
|
42 | not dead
|
43 | ```
|
44 |
|
45 | 2) Add script to `package.json`:
|
46 |
|
47 | ```json
|
48 | {
|
49 | "scripts": {
|
50 | "supportedBrowsers": "echo \"export default $(browserslist-useragent-regexp --allowHigherVersions);\" > supportedBrowsers.js"
|
51 | }
|
52 | }
|
53 | ```
|
54 |
|
55 | <details>
|
56 | <summary>for Windows users</summary>
|
57 |
|
58 | ```json
|
59 | {
|
60 | "scripts": {
|
61 | "supportedBrowsers": "(echo export default && browserslist-useragent-regexp --allowHigherVersions) > supportedBrowsers.js"
|
62 | }
|
63 | }
|
64 | ```
|
65 |
|
66 | </details>
|
67 |
|
68 | 3) Run this script, to compile regex:
|
69 |
|
70 | ```bash
|
71 | pnpm supportedBrowsers
|
72 | # or
|
73 | npm run supportedBrowsers
|
74 | # or
|
75 | yarn supportedBrowsers
|
76 | ```
|
77 |
|
78 | `supportedBrowsers.js`:
|
79 |
|
80 | ```js
|
81 | export default /Edge?\/(10[5-9]|1[1-9]\d|[2-9]\d\d|\d{4,})(\.\d+|)(\.\d+|)|Firefox\/(10[4-9]|1[1-9]\d|[2-9]\d\d|\d{4,})\.\d+(\.\d+|)|Chrom(ium|e)\/(10[5-9]|1[1-9]\d|[2-9]\d\d|\d{4,})\.\d+(\.\d+|)|Maci.* Version\/(15\.([6-9]|\d{2,})|(1[6-9]|[2-9]\d|\d{3,})\.\d+)([,.]\d+|)( Mobile\/\w+|) Safari\/|Chrome.+OPR\/(9\d|\d{3,})\.\d+\.\d+|(CPU[ +]OS|iPhone[ +]OS|CPU[ +]iPhone|CPU IPhone OS|CPU iPad OS)[ +]+(15[._]([6-9]|\d{2,})|(1[6-9]|[2-9]\d|\d{3,})[._]\d+)([._]\d+|)|Opera Mini|Android:?[ /\-](10[6-9]|1[1-9]\d|[2-9]\d{2}|\d{4,})(\.\d+|)(\.\d+|)|Mobile Safari.+OPR\/(6[4-9]|[7-9]\d|\d{3,})\.\d+\.\d+|Android.+Firefox\/(10[5-9]|1[1-9]\d|[2-9]\d\d|\d{4,})\.\d+(\.\d+|)|Android.+Chrom(ium|e)\/(10[6-9]|1[1-9]\d|[2-9]\d\d|\d{4,})\.\d+(\.\d+|)|Android.+(UC? ?Browser|UCWEB|U3)[ /]?(13\.([4-9]|\d{2,})|(1[4-9]|[2-9]\d|\d{3,})\.\d+)\.\d+|SamsungBrowser\/(1[7-9]|[2-9]\d|\d{3,})\.\d+|Android.+MQQBrowser\/(13(\.([1-9]|\d{2,})|)|(1[4-9]|[2-9]\d|\d{3,})(\.\d+|))(\.\d+|)|K[Aa][Ii]OS\/(2\.([5-9]|\d{2,})|([3-9]|\d{2,})\.\d+)(\.\d+|)/;
|
82 | ```
|
83 |
|
84 | 4) Import regex from created file:
|
85 |
|
86 | ```js
|
87 | import supportedBrowsers from './supportedBrowsers.js';
|
88 |
|
89 | if (supportedBrowsers.test(navigator.userAgent)) {
|
90 | alert('Your browser is supported.');
|
91 | }
|
92 | ```
|
93 |
|
94 | ## Install
|
95 |
|
96 | ```bash
|
97 | pnpm add -D browserslist-useragent-regexp
|
98 | # or
|
99 | npm i -D browserslist-useragent-regexp
|
100 | # or
|
101 | yarn add -D browserslist-useragent-regexp
|
102 | ```
|
103 |
|
104 | ## Why?
|
105 |
|
106 | As was written in article ["Smart Bundling: Shipping legacy code to only legacy browsers"](https://www.smashingmagazine.com/2018/10/smart-bundling-legacy-code-browsers/): you can determinate, which bundle you should give to browser from server with [`browserslist-useragent`](https://github.com/browserslist/browserslist-useragent). But in this case you must have your own server with special logic. Now, with `browserslist-useragent-regexp`, you can move that to client-side.
|
107 |
|
108 | Development was inspired by [this proposal from Mathias Bynens](https://twitter.com/mathias/status/1105857829393653761).
|
109 |
|
110 | How to make differential resource loading and other optimizations with `browserslist-useragent-regexp` you can read in article ["Speed up with Browserslist"](https://dev.to/dangreen/speed-up-with-browserslist-30lh).
|
111 |
|
112 | [Demo](https://browserslist.github.io/browserslist-useragent-regexp/demo.html) ([sources](https://github.com/browserslist/browserslist-useragent-regexp/blob/7cf6afb7da2b6c77179abb8b8bd1bbcb61cf376a/docs/demo.html#L17-L29), [build script](https://github.com/browserslist/browserslist-useragent-regexp/blob/7cf6afb7da2b6c77179abb8b8bd1bbcb61cf376a/examples/buildDemo.js#L61-L74)).
|
113 |
|
114 | Also, testing useragents using generated regex [is faster](https://gist.github.com/dangreen/55c41072d8891efd3a772a4739d6cd9d) than using the `matchesUA` method from browserslist-useragent.
|
115 |
|
116 | ## CLI
|
117 |
|
118 | ```bash
|
119 | pnpm browserslist-useragent-regexp [query] [...options]
|
120 | # or
|
121 | npx browserslist-useragent-regexp [query] [...options]
|
122 | # or
|
123 | yarn exec -- browserslist-useragent-regexp [query] [...options]
|
124 | ```
|
125 |
|
126 | Also, short alias is available:
|
127 |
|
128 | ```bash
|
129 | pnpm bluare [query] [...options]
|
130 | ```
|
131 |
|
132 | | Option | Description | Default |
|
133 | |--------|-------------|---------|
|
134 | | query | Manually provide a browserslist query. Specifying this overrides the browserslist configuration specified in your project. | |
|
135 | | ‑‑help, -h | Print this message. | |
|
136 | | ‑‑verbose, -v | Print additional info about regexes. | |
|
137 | | ‑‑ignorePatch | Ignore differences in patch browser numbers. | `true` |
|
138 | | ‑‑ignoreMinor | Ignore differences in minor browser versions. | `false` |
|
139 | | ‑‑allowHigherVersions | For all the browsers in the browserslist query, return a match if the useragent version is equal to or higher than the one specified in browserslist. | `false` |
|
140 | | ‑‑allowZeroSubversions | Ignore match of patch or patch and minor, if they are 0. | `false` |
|
141 |
|
142 | ## JS API basics
|
143 |
|
144 | Module exposes two main methods:
|
145 |
|
146 | ### [getUserAgentRegexes(options)](https://browserslist.github.io/browserslist-useragent-regexp/functions/getUserAgentRegexes.html)
|
147 |
|
148 | Compile browserslist query to [regexes for each browser](#regex-info-object).
|
149 |
|
150 | ### [getUserAgentRegex(options)](https://browserslist.github.io/browserslist-useragent-regexp/functions/getUserAgentRegex.html)
|
151 |
|
152 | Compile browserslist query to one regex.
|
153 |
|
154 | > [Description of all methods you can find in Documentation.](https://browserslist.github.io/browserslist-useragent-regexp/index.html)
|
155 |
|
156 | #### Options
|
157 |
|
158 | | Option | Type | Default | Description |
|
159 | |--------|------|---------|-------------|
|
160 | | browsers | `string \| string[]` | — | Manually provide a browserslist query (or an array of queries). Specifying this overrides the browserslist configuration specified in your project. |
|
161 | | ignorePatch | `boolean` | `true` | Ignore differences in patch browser numbers. |
|
162 | | ignoreMinor | `boolean` | `false` | Ignore differences in minor browser versions. |
|
163 | | allowHigherVersions | `boolean` | `false` | For all the browsers in the browserslist query, return a match if the useragent version is equal to or higher than the one specified in browserslist. |
|
164 | | allowZeroSubversions | `boolean` | `false` | Ignore match of patch or patch and minor, if they are 0. |
|
165 |
|
166 | Any of the [`browserslist` API options](https://github.com/browserslist/browserslist#js-api) may also be provided.
|
167 |
|
168 | #### Regex info object
|
169 |
|
170 | | Property | Type | Description |
|
171 | |----------|------|-------------|
|
172 | | family | `string` | Browser family. |
|
173 | | requestVersions | `[number, number, number][]` | Versions provided by browserslist. |
|
174 | | regex | `RegExp` | Regex to match useragent with family and versions. |
|
175 | | sourceRegex | `RegExp` | Original useragent regex, without versions. |
|
176 | | version | `[number, number, number] \| null` | Useragent version of regex. |
|
177 | | minVersion | `[number, number, number] \| null` | Useragent min version of regex. |
|
178 | | maxVersion | `[number, number, number] \| null` | Useragent max version of regex. |
|
179 |
|
180 | ## Other
|
181 |
|
182 | - [Supported browsers](https://github.com/browserslist/browserslist-useragent#supported-browsers)
|
183 | - [Notes](https://github.com/browserslist/browserslist-useragent#notes)
|
184 | - [When querying for modern browsers](https://github.com/browserslist/browserslist-useragent#when-querying-for-modern-browsers)
|