🚀 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

``shell
npm i -D nx-stylelint
`

using yarn

`shell
yarn add -D nx-stylelint
`

using pnpm

`shell
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.

`shell
nx g nx-stylelint:configuration --project
`

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:

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

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

`json
"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.

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

Examples

Run nx-stylelint for a project

`shell
nx stylelint {{projectName}}
`

Run nx-stylelint for all projects

`shell
nx run-many --target=stylelint
`

Run nx-stylelint for affected projects

`shell
nx affected --target=stylelint
`

📖 Documentation

nx-stylelint:configuration generator

Add stylelint configuration to a project.

$3

Add configuration to a project:

nx g nx-stylelint:configuration --project projectName

$3

| 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

$3

| 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 | true | 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:

`json
{
"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:

`json
{
"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 \|\| ^21.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` |