1 | # Writing formatters
|
2 |
|
3 | A formatter is a function with the following signature:
|
4 |
|
5 | ```js
|
6 | function formatter(results, returnValue) {
|
7 | return "a string of formatted results";
|
8 | }
|
9 | ```
|
10 |
|
11 | Where the first argument (`results`) is an array of stylelint result objects in the form:
|
12 |
|
13 | ```js
|
14 | // A stylelint result object
|
15 | {
|
16 | "source": "path/to/file.css", // The filepath or PostCSS identifier like <input css 1>
|
17 | "errored": true, // This is `true` if at least one rule with an "error"-level severity triggered a warning
|
18 | "warnings": [
|
19 | // Array of rule violation warning objects, each like the following ...
|
20 | {
|
21 | "line": 3,
|
22 | "column": 12,
|
23 | "rule": "block-no-empty",
|
24 | "severity": "error",
|
25 | "text": "You should not have an empty block (block-no-empty)"
|
26 | }
|
27 | ],
|
28 | "deprecations": [
|
29 | // Array of deprecation warning objects, each like the following ...
|
30 | {
|
31 | "text": "Feature X has been deprecated and will be removed in the next major version.",
|
32 | "reference": "https://stylelint.io/docs/feature-x.md"
|
33 | }
|
34 | ],
|
35 | "invalidOptionWarnings": [
|
36 | // Array of invalid option warning objects, each like the following ...
|
37 | {
|
38 | "text": "Invalid option X for rule Y"
|
39 | }
|
40 | ],
|
41 | "ignored": false // This is `true` if the file's path matches a provided ignore pattern
|
42 | }
|
43 | ```
|
44 |
|
45 | And the second argument (`returnValue`) is an object with one or more of the following keys:
|
46 |
|
47 | ```js
|
48 | {
|
49 | "errored": false, // `true` if there were any warnings with "error" severity
|
50 | "needlessDisables": [
|
51 | // Present if stylelint was configured with `reportNeedlessDisables: true`
|
52 | {
|
53 | "source": "path/to/file.css",
|
54 | "ranges": [
|
55 | {
|
56 | "start": 10,
|
57 | "unusedRule": "indentation"
|
58 | }
|
59 | ]
|
60 | }
|
61 | ],
|
62 | "invalidScopeDisables": [
|
63 | // Present if stylelint was configured with `reportInvalidScopeDisables: true`
|
64 | {
|
65 | "source": "path/to/file.css",
|
66 | "ranges": [
|
67 | {
|
68 | "start": 1,
|
69 | "unusedRule": "color-named"
|
70 | }
|
71 | ]
|
72 | }
|
73 | ],
|
74 | "maxWarningsExceeded": {
|
75 | // Present if stylelint was configured with a `maxWarnings` count
|
76 | "maxWarnings": 10,
|
77 | "foundWarnings": 15
|
78 | }
|
79 | }
|
80 | ```
|
81 |
|
82 | ## Passing arguments
|
83 |
|
84 | You can use environmental variables in your formatter. For example, pass `SKIP_WARNINGS`:
|
85 |
|
86 | ```console
|
87 | SKIP_WARNINGS=true stylelint "*.css" --custom-formatter ./my-formatter.js
|
88 | ```
|
89 |
|
90 | Alternatively, you can create a separate formatting program and pipe the output from the built-in JSON formatter into it:
|
91 |
|
92 | ```console
|
93 | stylelint -f json "*.css" | my-program-that-reads-JSON --option
|
94 | ```
|
95 |
|
96 | ## `stylelint.formatters`
|
97 |
|
98 | stylelint's internal formatters are exposed publicly in `stylelint.formatters`.
|