node-api.md

Node.js API

The Stylelint module includes a lint() function that provides the Node.js API.

stylelint.lint(options).then((resultObject) => {
  /* .. */
});

Options

In addition to the standard options, the Node API accepts:

config

A configuration object.

Stylelint does not bother looking for a .stylelintrc file if you use this option.

code

A string to lint.

cwd

The directory from which Stylelint will look for files. Defaults to the current working directory returned by process.cwd().

files

A file glob, or array of file globs.

Relative globs are considered relative to globbyOptions.cwd.

Though both files and code are "optional", you must have one and cannot have both.

globbyOptions

The options that are passed with files.

For example, you can set a specific cwd to use when globbing paths. Relative globs in files are considered relative to this path. By default, globbyOptions.cwd will be set by cwd.

For more detail usage, see Globby Guide.

The returned promise

stylelint.lint() returns a Promise that resolves with an object containing the following properties:

cwd

The directory used as the working directory for the linting operation.

errored

Boolean. If true, at least one rule with an "error"-level severity registered a problem.

output

A string that contains either the:

• formatted problems (using the default formatter or whichever you passed)
• or the autofixed code, if the fix option is set to true

postcssResults

An array containing all the accumulated PostCSS LazyResults.

results

An array containing all the Stylelint result objects (the objects that formatters consume).

maxWarningsExceeded

An object containing the maximum number of warnings and the amount found, e.g. { maxWarnings: 0, foundWarnings: 12 }.

Syntax errors

stylelint.lint() does not reject the Promise when your CSS contains syntax errors. It resolves with an object (see The returned promise) that contains information about the syntax error.

Usage examples

Example A

As config contains no relative paths for extends or plugins, you do not have to use configBasedir:

stylelint
  .lint({
    config: { rules: "color-no-invalid-hex" },
    files: "all/my/stylesheets/*.css"
  })
  .then((data) => {
    // do things with data.output, data.errored,
    // and data.results
  })
  .catch((err) => {
    // do things with err e.g.
    console.error(err.stack);
  });

Example B

If myConfig does contain relative paths for extends or plugins, you do have to use configBasedir:

stylelint
  .lint({
    config: myConfig,
    configBasedir: path.join(__dirname, "configs"),
    files: "all/my/stylesheets/*.css"
  })
  .then(() => {
    /* .. */
  });

Example C

Using a string instead of a file glob, and the verbose formatter instead of the default JSON:

stylelint
  .lint({
    code: "a { color: pink; }",
    config: myConfig,
    formatter: "verbose"
  })
  .then(() => {
    /* .. */
  });

Example D

Using your own custom formatter function and parse .scss source files:

stylelint
  .lint({
    config: myConfig,
    files: "all/my/stylesheets/*.scss",
    formatter: (stylelintResults) => {
      /* .. */
    }
  })
  .then(() => {
    /* .. */
  });

Example E

Using a custom syntax:

stylelint
  .lint({
    config: myConfig,
    files: "all/my/stylesheets/*.css",
    customSyntax: {
      parse: (css, opts) => {
        /* .. */
      },
      stringify: (root, builder) => {
        /* .. */
      }
    }
  })
  .then(() => {
    /* .. */
  });

Note that the customSyntax option also accepts a string. Refer to the options documentation for details.

Example F

Using a string and the fix option:

stylelint
  .lint({
    code: "a { color: pink; }",
    config: { rules: { "hue-degree-notation": "angle" } },
    fix: true
  })
  .then(() => {
    /* .. */
  });

The autofixed code will be available as the value of the output property in the returned object.

Resolving the effective config for a file

If you want to find out what exact configuration will be used for a file without actually linting it, you can use the resolveConfig() function. Given a file path, it will return a Promise that resolves with the effective configuration object:

const config = await stylelint.resolveConfig(filePath);

// config => {
//   rules: {
//     'color-no-invalid-hex': true
//   },
//   extends: [
//     'stylelint-config-standard',
//     'stylelint-config-css-modules'
//   ],
//   plugins: [
//     'stylelint-scss'
//   ],
//   …
// }

If a configuration cannot be found for a file, resolveConfig() will return a Promise that resolves to undefined.

You can also pass the following subset of the options that you would normally pass to lint():

• cwd
• config
• configBasedir
• customSyntax