.config/coc/extensions/node_modules/coc-prettier/node_modules/stylelint/docs/user-guide/node-api.md

   1 # The stylelint Node API
   2
   3 The stylelint module includes a `lint()` function that provides the Node API.
   4
   5 ```js
   6 stylelint.lint(options)
   7   .then(function(resultObject) { .. });
   8 ```
   9
  10 ## Installation
  11
  12 stylelint is an [npm package](https://www.npmjs.com/package/stylelint). Install it using:
  13
  14 ```console
  15 npm install stylelint
  16 ```
  17
  18 ## Options
  19
  20 Options is an object with the following properties.
  21
  22 Though both `files` and `code` are "optional", you *must* have one and *cannot* have both. All other options are optional.
  23
  24 ### `code`
  25
  26 A CSS string to be linted.
  27
  28 ### `codeFilename`
  29
  30 If using `code` to pass a source string directly, you can use `codeFilename` to associate that code with a particular filename.
  31
  32 This can be useful, for example, when making a text editor plugin that passes in code directly but needs to still use the configuration's `ignoreFiles` functionality to possibly ignore that code.
  33
  34 ### `config`
  35
  36 A [stylelint configuration object](configuration.md).
  37
  38 If no `config` or `configFile` is passed, stylelint will use a [config lookup algorithm](./configuration.md#loading-the-configuration-object) to find the correct config.
  39
  40 ### `configBasedir`
  41
  42 An absolute path to the directory that relative paths defining `extends` and `plugins` are *relative to*.
  43
  44 If the `config` object passed uses relative paths, e.g. for `extends` or `plugins`, you are going to have to pass a `configBasedir`. If not, you do not need this.
  45
  46 ### `configFile`
  47
  48 The path to a JSON, YAML, or JS file  that contains your [stylelint configuration object](configuration.md).
  49
  50 It should be either absolute or relative to the directory that your process is running from (`process.cwd()`). We'd recommend absolute.
  51
  52 ### `configOverrides`
  53
  54 A partial stylelint configuration object whose properties will override the existing config object, whether that config was loaded via the `config` option or a `.stylelintrc` file.
  55
  56 The difference between the `configOverrides` and `config` options is this: If any `config` object is passed, stylelint does not bother looking for a `.stylelintrc` file and instead just uses whatever `config` object you've passed; but if you want to *both* load a `.stylelintrc` file *and* override specific parts of it, `configOverrides` does just that.
  57
  58 ### `files`
  59
  60 A file glob, or array of file globs. Ultimately passed to [node-glob](https://github.com/isaacs/node-glob) to figure out what files you want to lint.
  61
  62 Relative globs are considered relative to `process.cwd()`.
  63
  64 By default, all `node_modules` and `bower_components` are ignored.
  65
  66 ### `formatter`
  67
  68 Options: `"json"|"string"|"verbose"`, or a function. Default is `"json"`.
  69
  70 Specify the formatter that you would like to use to format your results.
  71
  72 If you pass a function, it must fit the signature described in the [Developer Guide](../developer-guide/formatters.md).
  73
  74 ### `ignoreDisables`
  75
  76 If `true`, all disable comments (e.g. `/* stylelint-disable block-no-empty */`) will be ignored.
  77
  78 You can use this option to see what your linting results would be like without those exceptions.
  79
  80 ### `disableDefaultIgnores`
  81
  82 If `true`, stylelint will not automatically ignore the contents of `node_modules` and `bower_components`. (By default, these directories are automatically ignored.)
  83
  84 ### `cache`
  85
  86 Store the info about processed files in order to only operate on the changed ones the next time you run stylelint. Enabling this option can dramatically improve stylelint's speed, because only changed files will be linted.
  87
  88 By default, the cache is stored in `.stylelintcache` in `process.cwd()`. To change this, use the `cacheLocation` option.
  89
  90 **Note:** If you run stylelint with `cache` and then run stylelint without `cache`, the `.stylelintcache` file will be deleted. This is necessary because we have to assume that `.stylelintcache` was invalidated by that second command.
  91
  92 ### `cacheLocation`
  93
  94 A path to a file or directory to be used for `cache`. Only meaningful alongside `cache`. If no location is specified, `.stylelintcache` will be created in `process.cwd()`.
  95
  96 If a directory is specified, a cache file will be created inside the specified folder. The name of the file will be based on the hash of `process.cwd()` (e.g. `.cache_hashOfCWD`). This allows stylelint to reuse a single location for a variety of caches from different projects.
  97
  98 **Note:** If the directory of `cacheLocation` does not exist, make sure you add a trailing `/` on \*nix systems or `\` on Windows. Otherwise, the path will be assumed to be a file.
  99
 100 ### `reportNeedlessDisables`
 101
 102 If `true`, `ignoreDisables` will also be set to `true` and the returned data will contain a `needlessDisables` property, whose value is an array of objects, one for each source, with tells you which stylelint-disable comments are not blocking a lint violation.
 103
 104 Use this report to clean up your codebase, keeping only the stylelint-disable comments that serve a purpose.
 105
 106 *The recommended way to use this option is through the CLI.* It will output a clean report to the console.
 107
 108 ### `ignorePath`
 109
 110 A path to a file containing patterns describing files to ignore. The path can be absolute or relative to `process.cwd()`. By default, stylelint looks for `.stylelintignore` in `process.cwd()`. See [Configuration](configuration.md#stylelintignore).
 111
 112 ### `syntax`
 113
 114 Options: `"scss"|"less"|"sugarss"`
 115
 116 Specify a non-standard syntax that should be used to parse source stylesheets.
 117
 118 If you do not specify a syntax, non-standard syntaxes will be automatically inferred by the file extensions `.scss`, `.less`, and `.sss`.
 119
 120 See the [`customSyntax`](#customsyntax) option below if you would like to use stylelint with a custom syntax.
 121
 122 ### `customSyntax`
 123
 124 An absolute path to a custom [PostCSS-compatible syntax](https://github.com/postcss/postcss#syntaxes) module.
 125
 126 Note, however, that stylelint can provide no guarantee that core rules will work with syntaxes other than the defaults listed for the `syntax` option above.
 127
 128 ### `fix`
 129
 130 If `true`, stylelint will fix as many errors as possible. The fixes are made to the actual source files. All unfixed errors will be reported. See [Autofixing errors](cli.md#autofixing-errors) docs.
 131
 132 ## The returned promise
 133
 134 `stylelint.lint()` returns a Promise that resolves with an object containing the following properties:
 135
 136 ### `errored`
 137
 138 Boolean. If `true`, at least one rule with an "error"-level severity registered a violation.
 139
 140 ### `output`
 141
 142 A string displaying the formatted violations (using the default formatter or whichever you passed).
 143
 144 ### `postcssResults`
 145
 146 An array containing all the [PostCSS LazyResults](https://github.com/postcss/postcss/blob/master/docs/api.md#lazyresult-class) that were accumulated during processing.
 147
 148 ### `results`
 149
 150 An array containing all the stylelint result objects (the objects that formatters consume).
 151
 152 ## Syntax errors
 153
 154 `stylelint.lint()` does not reject the Promise when your CSS contains syntax errors.
 155 It resolves with an object (see [The returned promise](#the-returned-promise)) that contains information about the syntax error.
 156
 157 ## Usage examples
 158
 159 If `myConfig` contains no relative paths for `extends` or `plugins`, you do not have to use `configBasedir`:
 160
 161 ```js
 162 stylelint.lint({
 163   config: myConfig,
 164   files: "all/my/stylesheets/*.css"
 165 })
 166   .then(function(data) {
 167     // do things with data.output, data.errored,
 168     // and data.results
 169   })
 170   .catch(function(err) {
 171     // do things with err e.g.
 172     console.error(err.stack);
 173   });
 174 ```
 175
 176 If `myConfig` *does* contain relative paths for `extends` or `plugins`, you *do* have to use `configBasedir`:
 177
 178 ```js
 179 stylelint.lint({
 180   config: myConfig,
 181   configBasedir: path.join(__dirname, "configs"),
 182   files: "all/my/stylesheets/*.css"
 183 }).then(function() { .. });
 184 ```
 185
 186 Maybe you want to use a CSS string instead of a file glob, and you want to use the string formatter instead of the default JSON:
 187
 188 ```js
 189 stylelint.lint({
 190   code: "a { color: pink; }",
 191   config: myConfig,
 192   formatter: "string"
 193 }).then(function() { .. });
 194 ```
 195
 196 Maybe you want to use my own custom formatter function and parse `.scss` source files:
 197
 198 ```js
 199 stylelint.lint({
 200   config: myConfig,
 201   files: "all/my/stylesheets/*.scss",
 202   formatter: function(stylelintResults) { .. },
 203   syntax: "scss"
 204 }).then(function() { .. });
 205 ```
 206
 207 The same pattern can be used to read Less or [SugarSS](https://github.com/postcss/sugarss) syntax.