Skip to content

Latest commit

 

History

History
251 lines (185 loc) · 16.5 KB

README.md

File metadata and controls

251 lines (185 loc) · 16.5 KB
Raw

nx-stylelint Banner

nx-stylelint

Nx plugin to use Stylelint in your Nx workspace.

Nx peer dependency version Stylelint peer dependency version CI LICENSE npm version npm OpenSSF Scorecard

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

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