Skip to main content

Chapitre 56 : Linting et standardisation avec Stylelint

Application de règles de qualité sur le code CSS pour garantir la maintenabilité et la cohérence architecturale.

En tant que développeur Senior, vous savez que le CSS est l'un des langages les plus difficiles à maintenir à grande échelle. L'absence de typage fort et la nature globale des styles favorisent l'apparition de "dettes techniques visuelles" : propriétés redondantes, ordres de déclaration incohérents, sélecteurs trop complexes ou unités mal utilisées.

Le linting n'est pas une simple question d'esthétique (comme l'indentation), mais une stratégie de réduction des risques. Stylelint est l'outil standard de l'industrie pour automatiser cette surveillance.

Le Linting CSS avec Stylelint​

1. Quoi​

Stylelint est un linter (analyseur statique) puissant et extensible pour CSS, SCSS, Less et même CSS-in-JS. Contrairement à un formateur comme Prettier (qui s'occupe de la mise en forme), Stylelint analyse la sémantique et la qualité du code.

Il fonctionne en parcourant l'arbre de syntaxe abstraite (AST - Abstract Syntax Tree) de vos fichiers CSS pour vérifier si chaque déclaration respecte un ensemble de règles prédéfinies. Si une règle est enfreinte, Stylelint génère un avertissement (warning) ou une erreur (error).

2. Pourquoi​

Dans un projet professionnel, surtout en équipe, le linting répond à trois enjeux majeurs :

  1. Élimination des erreurs stupides : Détecter un color: #ffg; (hexadécimal invalide) ou une propriété inexistante avant même d'ouvrir le navigateur.
  2. Standardisation architecturale : Forcer l'utilisation de variables CSS plutôt que de valeurs "hardcodées", ou interdire l'usage de !important pour éviter les guerres de spécificité.
  3. Réduction de la charge cognitive : Lorsque tout le code suit la même structure (ordre des propriétés, nommage), le cerveau du développeur se concentre sur la logique métier et non sur la lecture du style.

3. Comment​

A. Installation et configuration minimale​

Pour démarrer, Stylelint nécessite l'installation du package core et généralement d'une configuration standard pour éviter de définir 100 règles manuellement.

npm install --save-dev stylelint stylelint-config-standard

Ensuite, on crée un fichier .stylelintrc.json à la racine du projet :

{
  "extends": "stylelint-config-standard",
  "rules": {
    "color-no-invalid-hex": true,
    "font-family-no-missing-generic-family-keyword": true
  }
}

B. Cas concret : Configuration Senior pour un Design System​

Un profil Senior ne se contente pas du "standard". Il configure Stylelint pour protéger l'architecture du projet. Voici une configuration robuste visant à imposer l'utilisation de variables et à limiter la complexité.

{
  "extends": [
    "stylelint-config-standard-scss"
  ],
  "rules": {
    "selector-max-id": 0, 
    "selector-max-type": 0,
    "max-nesting-depth": 3,
    "declaration-no-important": true,
    "color-named": "never",
    "unit-allowed-list": ["rem", "em", "px", "%", "vh", "vw"],
    "scss/at-rule-no-unknown": true
  }
}

Analyse des choix techniques :

  • selector-max-id: 0 : Interdit les IDs en CSS. Les IDs ont une spécificité trop élevée, rendant les styles impossibles à surcharger proprement.
  • selector-max-type: 0 : Encourage l'usage de classes plutôt que de balises (div, p), rendant le HTML interchangeable sans casser le style.
  • max-nesting-depth: 3 : Empêche l'imbrication excessive en SCSS, qui génère des sélecteurs trop longs et fragiles (effet "pyramide").
  • color-named: "never" : Force l'usage de codes Hex, RGB ou variables pour éviter les ambiguïtés des noms de couleurs CSS (ex: lightgrey vs silver).

Cycle de vie du Linting CSS​

C. Limitations et pièges​

Le linting n'est pas une solution miracle. Voici ses limites :

  • Conflits avec Prettier : Prettier gère le formatage (espaces, virgules), Stylelint gère la qualité. Si Stylelint demande un espace avant un bloc et que Prettier le supprime, vous entrez dans une boucle infinie de corrections.
    • Solution : Utiliser stylelint-config-prettier pour désactiver toutes les règles de Stylelint qui pourraient entrer en conflit avec Prettier.
  • Faux positifs : Certaines règles peuvent être trop restrictives pour des cas d'usage très spécifiques (ex: intégration d'une bibliothèque tierce).
    • Solution : Utiliser les commentaires de désactivation locale : /* stylelint-disable-next-line rule-name */.

Hiérarchie de Configuration Stylelint​

4. Zone de Danger​

❌ L'approche "Tout Interdire" Certains développeurs activent toutes les règles possibles, rendant le développement frustrant. Le linter devient un obstacle plutôt qu'une aide.

✅ L'approche "Progressive" Commencez par une config standard, puis ajoutez des règles strictes au fur et à mesure que vous identifiez des patterns problématiques dans vos revues de code.

❌ Ignorer le Linter en Local Lancer Stylelint uniquement dans la CI/CD. Le développeur découvre ses erreurs 5 minutes après le push, ce qui ralentit le cycle de feedback.

✅ L'intégration IDE + Git Hooks Installer l'extension Stylelint dans VS Code pour un feedback instantané et utiliser husky avec lint-staged pour empêcher le commit de code non valide.

Questions clés​

1. Quelle est la différence fondamentale entre Stylelint et Prettier ?

Découvrir la réponse

Prettier est un formatter : il s'occupe de l'aspect visuel (indentation, guillemets, retours à la ligne). Il ne juge pas si votre code est "correct" ou "performant". Stylelint est un linter : il analyse la qualité du code (interdiction des IDs, limitation de la profondeur d'imbrication, détection de propriétés invalides).

2. Comment gérer un cas exceptionnel où une règle de linting doit être ignorée ?

Découvrir la réponse

Il ne faut jamais modifier la configuration globale pour un cas unique. On utilise des commentaires spécifiques :

  • /* stylelint-disable rule-name */ : Désactive la règle pour tout le reste du fichier.
  • /* stylelint-disable-next-line rule-name */ : Désactive la règle uniquement pour la ligne suivante.

3. Pourquoi est-il recommandé d'interdire les sélecteurs de type (balises) dans un projet senior ?

Découvrir la réponse

L'utilisation de sélecteurs de type (div, section, h1) crée un couplage fort entre la structure HTML et le style. Si vous décidez de changer un div en section pour des raisons d'accessibilité (sémantique), vous risquez de casser le style. L'usage de classes (.card, .title) rend le style indépendant de la balise utilisée.

4. Qu'est-ce que l'option --fix de Stylelint ?

Découvrir la réponse

C'est une commande qui permet à Stylelint de corriger automatiquement toutes les violations de règles qui sont "auto-fixables" (comme l'ordre des propriétés, les espaces, ou certaines conversions d'unités), évitant ainsi des corrections manuelles fastidieuses.

Mise en pratique​

Exercice 1 : Mise en place et détection (Reproduction guidée)​

Objectif : Installer Stylelint et détecter des erreurs basiques.

  1. Initialisez un projet npm.
  2. Installez stylelint et stylelint-config-standard.
  3. Créez un fichier .stylelintrc.json qui étend stylelint-config-standard.
  4. Créez un fichier style.css contenant volontairement :
    • Une couleur hexadécimale invalide (ex: #zz0011).
    • Une propriété CSS inexistante (ex: color-font: red;).
    • Un sélecteur avec un ID (ex: #main-header { ... }).
  5. Lancez Stylelint en ligne de commande et listez les erreurs trouvées.
Découvrir la solution commentée
# 1 & 2. Installation
npm init -y
npm install --save-dev stylelint stylelint-config-standard

# 3. .stylelintrc.json
# {
#   "extends": "stylelint-config-standard"
# }

# 4. style.css
# #main-header {
#   color: #zz0011;
#   color-font: red;
# }

# 5. Exécution
# npx stylelint "style.css"

Exercice 2 : Durcissement de la configuration (Adaptation)​

Objectif : Créer une configuration restrictive pour un projet d'entreprise.

Modifiez votre fichier .stylelintrc.json pour ajouter les contraintes suivantes :

  1. Interdire totalement l'usage de !important.
  2. Interdire l'usage des unités px pour les propriétés font-size (pour forcer l'usage de rem ou em pour l'accessibilité).
  3. Limiter la profondeur d'imbrication à 2 niveaux (nécessite l'installation de stylelint-config-standard-scss et l'utilisation d'un fichier .scss).
Découvrir la solution commentée
{
  "extends": "stylelint-config-standard-scss",
  "rules": {
    "declaration-no-important": true,
    "declaration-property-unit-disallowed-list": {
      "font-size": ["px"]
    },
    "max-nesting-depth": 2
  }
}

Exercice 3 : Architecture et Workflow CI (Conception)​

Objectif : Concevoir un workflow de validation CSS.

Imaginez que vous travaillez sur un projet avec 10 développeurs. Vous devez mettre en place un système où :

  1. Le code est vérifié avant chaque commit.
  2. Le code est vérifié lors de chaque Pull Request sur GitHub.
  3. Les erreurs de formatage sont corrigées automatiquement.

Question : Quels outils utilisez-vous et comment les configurez-vous ? (Décrivez la solution ou fournissez les fichiers de configuration).

Découvrir la solution commentée

Pour répondre à ce besoin, on met en place le trio Husky + lint-staged + GitHub Actions.

1. Husky & lint-staged (Pré-commit) On installe husky et lint-staged pour ne lint-er que les fichiers modifiés (gain de performance).

// package.json
{
  "lint-staged": {
    "*.{css,scss}": [
      "stylelint --fix"
    ]
  }
}

2. GitHub Actions (CI) On crée un workflow .github/workflows/lint.yml qui échoue si Stylelint trouve des erreurs.

name: Lint CSS
on: [pull_request]
jobs:
  stylelint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
        with:
          node-version: '18'
      - run: npm install
      - run: npx stylelint "**/*.css"

3. Automatisation L'option --fix dans lint-staged assure que les erreurs simples sont corrigées avant même que le code ne quitte la machine du développeur.