Comment linter votre CSS avec Stylelint

May 4, 2026 · 4 min read

Un CSS désordonné est facile à écrire et difficile à maintenir. Des propriétés mal orthographiées, des sélecteurs en double et des conventions incohérentes passent inaperçus lors des revues de code et s’accumulent en dette technique. Stylelint résout ce problème en détectant les erreurs et en appliquant les standards automatiquement — avant qu’ils n’atteignent la production.

Ce guide couvre tout ce dont vous avez besoin pour faire fonctionner le linting CSS avec Stylelint dans votre projet dès aujourd’hui.

Points clés à retenir

Stylelint détecte les erreurs CSS et applique les conventions grâce à l’analyse statique, avec plus de 100 règles intégrées.
Il gère la qualité du code, pas le formatage, ce qui le rend naturellement complémentaire à Prettier plutôt que concurrent.
L’installation la plus rapide se fait via npm create stylelint@latest, qui génère une configuration et installe stylelint-config-standard.
Les règles peuvent être activées, désactivées ou rétrogradées en avertissements — utile lors de l’adoption de Stylelint sur des bases de code existantes.
Intégrez-le dans un script npm et un pipeline CI pour garantir que le linting est réellement exécuté.

Qu’est-ce que Stylelint et pourquoi a-t-il sa place dans votre flux de travail ?

Stylelint est un linter CSS comportant plus de 100 règles intégrées, utilisé avec confiance par les équipes de Google et GitHub. Il analyse statiquement vos fichiers CSS et signale les problèmes — syntaxe invalide, propriétés inconnues, sélecteurs en double et violations de conventions — sans exécuter le code.

Une distinction importante : Stylelint gère la qualité du code, pas le formatage. Il n’entrera pas en conflit avec Prettier au sujet des espaces ou des points-virgules. Les deux outils sont complémentaires. Prettier formate, tandis que Stylelint applique l’exactitude et la cohérence. Utilisez les deux.

Installer Stylelint : deux façons de démarrer

Stylelint nécessite une version récente de Node.js (Node 20.19.0 ou plus récent dans les versions actuelles), assurez-vous donc que votre environnement est à jour.

Option 1 : Installation automatisée (recommandée)

Le moyen le plus rapide de linter du CSS avec Stylelint est la commande create :

npm create stylelint@latest

Cela génère un fichier de configuration et installe automatiquement stylelint-config-standard. Cela fonctionne également avec pnpm, Yarn et Bun :

pnpm create stylelint
bun create stylelint

Option 2 : Installation manuelle de Stylelint

Si vous préférez avoir un contrôle total, installez les dépendances vous-même :

npm add -D stylelint stylelint-config-standard

Ensuite, créez un fichier stylelint.config.mjs à la racine de votre projet :

/** @type {import('stylelint').Config} */
export default {
  extends: ["stylelint-config-standard"]
};

L’extension .mjs utilise ESM — le format de module moderne. Stylelint prend en charge la configuration ESM, qui est l’approche recommandée dans les configurations actuelles.

Exécuter Stylelint sur vos fichiers CSS

Une fois installé, exécutez Stylelint sur tous les fichiers CSS :

npx stylelint "**/*.css"

Vous obtiendrez un résultat de ce type pour toute violation :

src/main.css
  12:3  ✖  Unexpected duplicate selector ".btn"   no-duplicate-selectors
  24:5  ✖  Unknown property "colour"              property-no-unknown

Pour corriger automatiquement ce qui peut l’être, ajoutez le drapeau --fix :

npx stylelint "**/*.css" --fix

Toutes les règles ne prennent pas en charge la correction automatique, mais beaucoup le font. Le drapeau --fix applique des corrections sûres lorsque c’est possible, mais il ne résoudra pas tous les problèmes.

Configurer les règles de linting CSS de Stylelint

stylelint-config-standard constitue une base solide. Vous pouvez l’étendre et remplacer des règles spécifiques dans votre configuration :

/** @type {import('stylelint').Config} */
export default {
  extends: ["stylelint-config-standard"],
  rules: {
    "color-no-invalid-hex": true,
    "unit-no-unknown": true,
    "selector-id-pattern": null  // disable a rule
  }
};

Les règles acceptent true pour activer, null pour désactiver, ou un tableau pour configurer la sévérité :

"color-no-invalid-hex": [true, { severity: "warning" }]

C’est utile lors de l’introduction de Stylelint dans une base de code existante — les avertissements vous permettent d’auditer les problèmes sans bloquer immédiatement les builds.

Ajouter un script de linting à package.json

Intégrez Stylelint dans votre flux de travail avec un script npm :

{
  "scripts": {
    "lint:css": "stylelint \"**/*.css\""
  }
}

Exécutez-le avec npm run lint:css. À partir de là, vous pouvez l’intégrer à votre pipeline CI ou à des hooks pre-commit en utilisant lint-staged et Husky.

Bonnes pratiques pour le linting CSS

Commencez avec stylelint-config-standard — il reflète les bonnes pratiques CSS actuelles et est activement maintenu.
Utilisez des avertissements avant les erreurs lors de l’adoption de Stylelint sur du code legacy.
Ignorez les fichiers générés en ajoutant un fichier .stylelintignore (similaire à .gitignore).
Associez-le à Prettier — n’essayez pas d’utiliser Stylelint pour le formatage.
Exécutez-le en CI — un linting effectué uniquement sur les machines locales finit par être ignoré.

Conclusion

Stylelint prend environ cinq minutes à configurer et porte ses fruits immédiatement avec des erreurs détectées et un code cohérent. Installez-le, étendez stylelint-config-standard, ajoutez un script et exécutez-le. C’est toute la configuration. Tout le reste — règles personnalisées, prise en charge de SCSS, intégration avec l’IDE — s’appuie sur cette base.

FAQ

Oui. Stylelint prend en charge SCSS, Less et d'autres syntaxes similaires au CSS via des syntaxes personnalisées telles que `postcss-scss` ou `postcss-less`. La prise en charge de CSS-in-JS dépend de la bibliothèque spécifique et nécessite le package de syntaxe personnalisée approprié configuré via l'option `customSyntax`.

Oui, ils résolvent des problèmes différents. Prettier formate votre code, en gérant les espaces, les sauts de ligne et le style des guillemets. Stylelint détecte les problèmes de qualité de code comme les propriétés invalides, les sélecteurs en double et les violations de conventions. Le Stylelint moderne a supprimé ses règles stylistiques spécifiquement pour éviter les chevauchements avec Prettier, de sorte que les deux outils fonctionnent ensemble sans conflits.

Utilisez lint-staged avec Husky. Configurez lint-staged dans package.json pour exécuter stylelint --fix sur les fichiers CSS en zone de staging, puis ajoutez un hook pre-commit Husky qui appelle lint-staged. Cela lint uniquement les fichiers sur le point d'être committés, gardant le hook rapide même dans les gros dépôts tout en empêchant un CSS problématique d'atteindre la branche principale.

Oui. VS Code dispose d'une extension Stylelint officielle qui met en évidence les problèmes au fur et à mesure que vous tapez et peut les corriger lors de l'enregistrement. WebStorm et les autres IDE de JetBrains incluent une prise en charge intégrée de Stylelint. D'autres éditeurs peuvent avoir des intégrations soutenues par la communauté. L'intégration à l'éditeur raccourcit considérablement la boucle de rétroaction par rapport à l'exécution manuelle de la CLI.

Complete picture for complete understanding

Capture every clue your frontend is leaving so you can instantly get to the root cause of any issue with OpenReplay — the open-source session replay tool for developers. Self-host it in minutes, and have complete control over your customer data.

Check our GitHub repo and join the thousands of developers in our community.