Skip to main content

Getting Started

This guide gets you from zero to a production-safe baseline quickly.

Prerequisitesโ€‹

  • ESLint with Flat Config
  • Stylelint installed in the same project
  • A stylelint config file (for example stylelint.config.mjs)

Step 1: Install dependenciesโ€‹

npm install --save-dev eslint-plugin-stylelint-2 stylelint

Step 2: Start with one presetโ€‹

Pick one adoption mode:

  • Bridge only (just run Stylelint from ESLint): stylelintOnly
  • Bridge + config quality (recommended for teams): recommended

Example eslint.config.mjs:

import stylelint2 from "eslint-plugin-stylelint-2";

export default [
  stylelint2.configs.recommended,
  {
    rules: {
      // Optional: tune bridge behavior here.
      "stylelint2/stylelint": "error",
    },
  },
];

Step 3: Run lint once and apply fixesโ€‹

npx eslint . --fix

Review the PR diff and categorize findings:

  1. Safe autofixes (accept immediately)
  2. Configuration cleanups (plan staged rollout)
  3. Actual style violations (fix or suppress with rationale)

Step 4: Configure the bridge rule intentionallyโ€‹

If your project needs custom syntax or special file matching, tune the stylelint rule.

Typical options include:

  • customSyntax
  • configFile
  • configBasedir
  • quiet
  • allowEmptyInput

Step 5: Roll out in phasesโ€‹

Recommended rollout model:

  1. Enable preset + run in CI as warning-only (short period)
  2. Resolve baseline issues
  3. Switch to error-level enforcement
  4. Add stricter config-authoring rules over time

Common rollout mistakesโ€‹

  • Enabling all immediately: high noise and slower adoption
  • Mixing Stylelint CLI and ESLint bridge outputs in the same CI gate without clear ownership
  • Skipping autofix pass before triage

Where to go nextโ€‹