nx-stylelint

Nx plugin to use Stylelint in your Nx workspace.

🚀 Features

nx-stylelint provides a set of power-ups for Nx to lint your projects with Stylelint.

• Plugin: Provides a experimental plugin to infer your stylelint target when a configuration file exists.
• Executor: Provides an executor to lint your styles with Stylelint.
• Generators: Helping you to configure your projects.
• Configuration: Per Project configuration of Stylelint extending a workspace configuration.
• Only Affected: Uses Nx to support linting only affected projects.
• Cache: Uses Nx to cache already linted projects.

📦 Installation

using npm

npm i -D nx-stylelint

using yarn

yarn add -D nx-stylelint

using pnpm

pnpm add -D nx-stylelint

🛠️ Configuring Stylelint for a project

To add a stylelint configuration to a project you just have to run the nx-stylelint:configuration generator.

nx g nx-stylelint:configuration --project <projectName>

The generator adds a .stylelintrc.json at the project root which extends the root .stylelintrc.json and adds a stylelint target to the project.

At the first run the generator installs all required dependencies and creates a .stylelintrc.json file at the workspace root. It also configures the namedInputs for the stylelint targets.

Using the Experimental Plugin

Read the official NX docs to understand Infered Tasks: https://nx.dev/concepts/inferred-tasks

Adding the plugin is currently not supported by the generators.

To add the plugin add the following to your nx.json:

{
  "plugins": [
    {
      "plugin": "nx-stylelint/plugin",
      "options": {
        "targetName": "stylelint",
        "extensions": ["css"]
      }
    }
  ]
}

targetDefaults can be configured e.g. --allow-empty-input:

"targetDefaults": {
    "stylelint": {
        "options": {
            "args": ["--allow-empty-input"]
        }
    }
}

You don't need a stylelint target in your project.json files anymore. If you want to configure options for a single project provide the target and add the stylelint CLI arguments as documented at https://stylelint.io/user-guide/cli#options.

"targets": {
    "stylelint": {
        "options": {
            "args": [
                "--report-descriptionless-disables"
            ]
        }
    }
}

Examples

Run nx-stylelint for a project

nx stylelint {{projectName}}

Run nx-stylelint for all projects

nx run-many --target=stylelint

Run nx-stylelint for affected projects

nx affected --target=stylelint

📖 Documentation

nx-stylelint:configuration generator

Add stylelint configuration to a project.

Usage

Add configuration to a project:

nx g nx-stylelint:configuration --project projectName

Options

| Option | Value | Description | | ------------ | --------------------------------------------------------------------------- | ------------------------------------------------------------------------------------- | | formatter | compact | github | json | string | tap | unix | verbose | Stylelint Output formatter (https://stylelint.io/user-guide/usage/options#formatter). | | project | string | The name of the project. | | scss | boolean | Add SCSS Language support. | | skipFormat | boolean | Skip formatting files. |

nx-stylelint:lint executor

Run stylelint on a project.

Target Options can be configured in project.json or when the executor is invoked.

See: https://nx.dev/configuration/projectjson#targets

Options

| Option | Value | Default | Description | | ------------------------------- | ---------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | allowEmptyInput | boolean | true | The executor exits without throwing an error when 'lintFilePatterns' match no files. | | cache | boolean | false | Store the results of processed files so that Stylelint only operates on the changed ones. | | cacheLocation | string | | Path to a file or directory for the cache location. | | configFile | string | | Path to a stylelint configuration file. | | fix | boolean | false | Fixes linting errors (may overwrite linted files). | | force | boolean | false | Succeeds even if there were linting errors. | | formatter | string | string | Specify the formatter to format your results (Stylelint Docs). compact | github | json | string | tap | unix | verbose or a npm package (e.g. stylelint-formatter-pretty) or a path to a local formatter (e.g. tools/stylelint-formatter.js) | | ignoreDisables | boolean | false | Ignore stylelint-disable comments. | | ignorePath | string | | 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(). | | lintFilePatterns | string[] | | One or more files/dirs/globs to pass directly to Stylelint's lint() method. | | maxWarnings | number | | Number of warnings to trigger a nonzero exit code. | | outputFile | string | | File to write the report to. | | quiet | boolean | false | Only register problems for rules with an "error"-level severity (ignore "warning"-level). | | reportDescriptionlessDisables | boolean | false | Report stylelint-disable comments without a description. | | reportInvalidScopeDisables | boolean | false | Report stylelint-disable comments that don't match rules that are specified in the configuration object. | | reportNeedlessDisables | boolean | false | Report stylelint-disable comments that don't actually match any lints that need to be disabled. | | silent | boolean | false | Hide output text. |

Custom Formatters

nx-stylelint supports custom stylelint formatters. You can either install them with your package manager or write your own formatter.

For a guide on writing custom formatters see: https://stylelint.io/developer-guide/formatters

For a list of installable formatters take a look at:

• https://github.com/stylelint/awesome-stylelint#formatters
• https://www.npmjs.com/search?q=stylelint-formatter

Usage

To use a custom formatter you have to configure the formatter option of your stylelint target. Target Options can be configured in the project.json file of your project or when invoking it (https://nx.dev/configuration/projectjson#targets).

You can provide a path to your custom formatter:

{
  "projectType": "library",
  "sourceRoot": "libs/styles/src",
  "targets": {
    "stylelint": {
      "executor": "nx-stylelint:lint",
      "outputs": ["{options.outputFile}"],
      "options": {
        "lintFilePatterns": ["libs/styles/**/*.css"],
        "formatter": "tools/my-own-stylelint-formatter.js"
      }
    }
  }
}

Or the name of your installed formatter package e.g. stylelint-formatter-pretty. Scoped packages are also supported:

{
  "projectType": "library",
  "sourceRoot": "libs/styles/src",
  "targets": {
    "stylelint": {
      "executor": "nx-stylelint:lint",
      "outputs": ["{options.outputFile}"],
      "options": {
        "lintFilePatterns": ["libs/styles/**/*.css"],
        "formatter": "stylelint-formatter-pretty"
      }
    }
  }
}

Compatibility with Nx and Stylelint

nx-stylelint depends on Nx and Stylelint. This table provides the compatibility matrix between versions of nx-stylelint, Nx and Stylelint.

| nx-stylelint Version | Nx Version | Stylelint Version | | -------------------- | ----------------------------------- | ---------------------- | | ^18.0.0 | ^19.0.0 \|\| ^20.0.0 | ^16.0.0 | | ^17.1.0 | ^17.0.0 \|\| ^18.0.0 \|\| ^19.0.0 | ^15.0.0 \|\| ^16.0.0 | | ^17.0.0 | ^17.0.0 \|\| ^18.0.0 | ^15.0.0 | | ^16.0.0 | ^16.0.0 | ^15.0.0 | | ^15.0.0 | ^15.0.0 | ^15.0.0 | | ^14.0.0 | ^14.0.0 | ^14.10.0 | | ^13.0.0 | >=12.0.0 | ^14.0.0 | | ^12.0.0 | >=12.0.0 | ^13.0.0 | | ^11.0.0 | ^11.0.0 | ^13.0.0 |