1 | [![Build Status](https://travis-ci.org/anandthakker/doiuse.svg?branch=master)](https://travis-ci.org/anandthakker/doiuse)
|
2 | [![Release Notes](https://release-notes.com/badges/v2.svg)](https://release-notes.com/@open-source-community/anandthakker-doiuse)
|
3 |
|
4 | # doiuse
|
5 |
|
6 | Lint CSS for browser support against [Can I use](http://caniuse.com) database.
|
7 |
|
8 | ## Install
|
9 |
|
10 | ```sh
|
11 | npm install -g doiuse
|
12 | ```
|
13 |
|
14 | ## Usage Examples
|
15 |
|
16 | ### Command Line
|
17 |
|
18 | ```bash
|
19 | doiuse --browsers "ie >= 9, > 1%, last 2 versions" main.css
|
20 | # or
|
21 | cat main.css | doiuse --browsers "ie >= 9, > 1%, last 2 versions"
|
22 | ```
|
23 |
|
24 | **Sample output:**
|
25 | ```
|
26 | /projects/website/main.css:5:3: CSS3 Box-sizing not supported by: IE (8,9,10,11), Chrome (36,37,38), Safari (8,7.1), Opera (24,25), iOS Safari (8,7.1,8.1), Android Browser (4.1,4.4,4.4.4), IE Mobile (10,11)
|
27 | /projects/website/main.css:6:3: CSS3 Box-sizing not supported by: IE (8,9,10,11), Chrome (36,37,38), Safari (8,7.1), Opera (24,25), iOS Safari (8,7.1,8.1), Android Browser (4.1,4.4,4.4.4), IE Mobile (10,11)
|
28 | /projects/website/main.css:8:3: CSS user-select: none not supported by: IE (8,9)
|
29 | /projects/website/main.css:9:3: CSS user-select: none not supported by: IE (8,9)
|
30 | /projects/website/main.css:10:3: CSS user-select: none not supported by: IE (8,9)
|
31 | /projects/website/main.css:11:3: CSS user-select: none not supported by: IE (8,9)
|
32 | /projects/website/main.css:12:3: CSS user-select: none not supported by: IE (8,9)
|
33 | /projects/website/main.css:13:3: Pointer events not supported by: IE (8,9,10), Firefox (32,33), Chrome (36,37,38), Safari (8,7.1), Opera (24,25), iOS Safari (8,7.1,8.1), Android Browser (4.1,4.4,4.4.4), IE Mobile (10)
|
34 | /projects/website/main.css:14:3: Pointer events not supported by: IE (8,9,10), Firefox (32,33), Chrome (36,37,38), Safari (8,7.1), Opera (24,25), iOS Safari (8,7.1,8.1), Android Browser (4.1,4.4,4.4.4), IE Mobile (10)
|
35 | /projects/website/main.css:32:3: CSS3 Transforms not supported by: IE (8)
|
36 | ```
|
37 |
|
38 | Use `--json` to get output as (newline-delimited) JSON objects.
|
39 |
|
40 | ### JS
|
41 |
|
42 | ```javascript
|
43 | import postcss from 'postcss';
|
44 | import DoIUse from 'doiuse/lib/DoIUse.js';
|
45 |
|
46 | postcss(new DoIUse({
|
47 | browsers:['ie >= 6', '> 1%'],
|
48 | ignore: ['rem'], // an optional array of features to ignore
|
49 | ignoreFiles: ['**/normalize.css'], // an optional array of file globs to match against original source file path, to ignore
|
50 | onFeatureUsage: (usageInfo) => {
|
51 | console.log(usageInfo.message);
|
52 | }
|
53 | })).process("a { background-size: cover; }")
|
54 | ```
|
55 |
|
56 | CommonJS syntax is still supported if using `var doiuse = require('doiuse')`.
|
57 |
|
58 | ### Gulp (CommonJS)
|
59 |
|
60 | ```javascript
|
61 | var gulp = require('gulp')
|
62 | var postcss = require('postcss')
|
63 | var doiuse = require('doiuse')
|
64 |
|
65 | gulp.src(src, { cwd: process.cwd() })
|
66 | .pipe(gulp.postcss([
|
67 | doiuse({
|
68 | browsers: [
|
69 | 'ie >= 8',
|
70 | '> 1%'
|
71 | ],
|
72 | ignore: ['rem'], // an optional array of features to ignore
|
73 | ignoreFiles: ['**/normalize.css'], // an optional array of file globs to match against original source file path, to ignore
|
74 | onFeatureUsage: function (usageInfo) {
|
75 | console.log(usageInfo.message)
|
76 | }
|
77 | })
|
78 | ]))
|
79 | ```
|
80 |
|
81 | ## How it works
|
82 |
|
83 | In particular, the approach to detecting features usage is currently quite naive.
|
84 |
|
85 | <a name="features-list"></a>Refer to the data in [/data/features.js](data/features.js).
|
86 |
|
87 | - If a feature in that dataset only specifies `properties`, we just use those
|
88 | properties for regex/substring matches against the properties used in the input CSS.
|
89 | - If a feature also specifies `values`, then we also require that the associated
|
90 | value matches one of those values.
|
91 |
|
92 | ## API Details
|
93 |
|
94 | ### As a transform stream
|
95 |
|
96 | ```javascript
|
97 | var doiuse = require('doiuse/stream');
|
98 |
|
99 | process.stdin
|
100 | .pipe(doiuse({ browsers: ['ie >= 8', '> 1%'], ignore: ['rem'] }))
|
101 | .on('data', function (usageInfo) {
|
102 | console.log(JSON.stringify(usageInfo))
|
103 | })
|
104 | ```
|
105 |
|
106 | Yields `UsageInfo` objects as described below.
|
107 |
|
108 | ### As a postcss plugin
|
109 |
|
110 | `postcss(new DoIUse(opts)).process(css)`, where `opts` is:
|
111 | ```javascript
|
112 | {
|
113 | browsers: ['ie >= 8', '> 1%'], // an autoprefixer-like array of browsers.
|
114 | ignore: ['rem'], // an optional array of features to ignore
|
115 | ignoreFiles: ['**/normalize.css'], // an optional array of file globs to match against original source file path, to ignore
|
116 | onFeatureUsage: function(usageInfo) { } // a callback for usages of features not supported by the selected browsers
|
117 | }
|
118 | ```
|
119 |
|
120 | And `usageInfo` looks like this:
|
121 |
|
122 | ```javascript
|
123 | {
|
124 | message: '<input source>: line <l>, col <c> - CSS3 Gradients not supported by: IE (8)',
|
125 | feature: 'css-gradients', // slug identifying a caniuse-db feature
|
126 | featureData: {
|
127 | title: 'CSS Gradients',
|
128 | missing: "IE (8)", // string of browsers missing support for this feature.
|
129 | missingData: {
|
130 | // map of browser -> version -> (lack of)support code
|
131 | ie: { '8': 'n' }
|
132 | },
|
133 | caniuseData: { // data from caniuse-db/features-json/[feature].json }
|
134 | },
|
135 | usage: {} //the postcss node where that feature is being used.
|
136 | }
|
137 | ```
|
138 |
|
139 | Called once for each usage of each css feature not supported by the selected browsers.
|
140 |
|
141 | ### Ignoring file-specific rules
|
142 |
|
143 | For disabling some checks you can use just-in-place comments
|
144 |
|
145 | ##### `/* doiuse-disable */`
|
146 |
|
147 | Disables checks of _all [features](#features-list)_
|
148 |
|
149 | ##### `/* doiuse-disable feature */`
|
150 |
|
151 | Disables checks of _specified [feature(s)](#features-list)_ (can be comma separated list)
|
152 |
|
153 | ##### `/* doiuse-enable */`
|
154 |
|
155 | Re-enables checks of _all [features](#features-list)_
|
156 |
|
157 | ##### `/* doiuse-enable feature */`
|
158 |
|
159 | Enables checks of _specified [feature(s)](#features-list)_ (can be comma separated list)
|
160 | - for following lines in file
|
161 |
|
162 | ## [Contributing](CONTRIBUTING.md)
|
163 |
|
164 | doiuse is an [OPEN Open Source](http://openopensource.org/) Project.
|
165 |
|
166 | This means that individuals making significant and valuable contributions are given commit-access to the project to contribute as they see fit. This project is more like an open wiki than a standard guarded open source project.
|
167 |
|
168 | ## License
|
169 |
|
170 | MIT
|
171 |
|
172 | **NOTE:** Many of the files in test/cases are from autoprefixer-core, Copyright 2013 Andrey Sitnik <andrey@sitnik.ru>. Please see https://github.com/postcss/autoprefixer-core.
|