nx-stylelint v18.0.0

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

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

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.