Skip to main content

Config Authoring

Bridge execution solves "how to run Stylelint from ESLint." Config authoring rules solve "how to keep Stylelint config files maintainable over time."

Why config quality rules matterโ€‹

In larger repositories, stylelint config drift usually appears as:

  • duplicated extends / plugins
  • inconsistent array ordering
  • hidden relative path assumptions
  • stale override blocks

The config rule set helps keep config files deterministic and review-friendly.

Start with recommended, then strengthen incrementally.

A practical progression:

  1. Deduplication and shape rules (require-*, disallow-* basics)
  2. Sorting rules for stable diffs
  3. Environment-specific hardening (monorepo path/package checks)

Authoring conventions that scaleโ€‹

1) Keep extends and plugins explicitโ€‹

  • Avoid implicit path behavior
  • Prefer package-based references where possible
  • Enforce package-install checks with dedicated rules

2) Keep arrays deterministicโ€‹

Use sorting rules to minimize merge churn:

3) Treat overrides as policy, not exceptionsโ€‹

Enforce consistent override structure and file targeting:

4) Prevent legacy/deprecated patternsโ€‹

Guard against obsolete or risky stylelint config patterns with disallow-* rules.

Monorepo tipsโ€‹

  • Keep configBasedir stable when invoking bridge rule options.
  • Avoid relative extends/plugin path assumptions between packages.
  • Validate package dependencies where stylelint config references plugins/presets.

Migration strategy for existing reposโ€‹

  1. Enable config rules in warning mode first.
  2. Apply autofixes and sorting.
  3. Resolve remaining hard violations in batches.
  4. Promote to error once baseline debt is cleared.