Safelisting

Vous pouvez indiquer quels sélecteurs peuvent être conservés en toute sécurité dans le CSS final. Cela peut être accompli avec l'option PurgeCSS safelist, ou directement dans votre CSS avec un commentaire spécial.

Noms de classes construits à l'exécution

PurgeCSS n'exécute pas votre code. Il lit vos fichiers de contenu comme du texte et conserve les sélecteurs dont les noms y apparaissent. Un nom de classe qui n'existe qu'à l'exécution de votre code, parce qu'il est construit avec un template literal ou en concaténant des chaînes de caractères, n'est jamais trouvé, et son CSS est supprimé.

// PurgeCSS trouve `btn` et `btn-`, mais pas `btn-primary` ni `btn-danger`
const className = `btn btn-${variant}`;

Écrivez les noms de classes complets dans vos fichiers de contenu, pour que PurgeCSS puisse les trouver :

const variants = {
  primary: "btn-primary",
  danger: "btn-danger",
};
const className = `btn ${variants[variant]}`;

Ou, si vous ne pouvez pas les lister, ajoutez-les à la safelist avec un motif :

const purgeCSSResult = await new PurgeCSS().purge({
    content: [], // contenu
    css: [], // css
    safelist: [/^btn-/]
})

Sélecteurs spécifiques

Vous pouvez ajouter des sélecteurs à la safelist avec safelist.

const purgeCSSResult = await new PurgeCSS().purge({
    content: [], // contenu
    css: [], // css
    safelist: ['random', 'yep', 'button']
})

Dans cet exemple, les sélecteurs .random, #yep, button seront conservés dans le CSS final.

Motifs

Vous pouvez ajouter des sélecteurs à la safelist en fonction d'une expression régulière avec safelist.standard, safelist.deep et safelist.greedy.

const purgeCSSResult = await new PurgeCSS().purge({
    content: [], // contenu
    css: [], // css
    safelist: {
      standard: [/red$/],
      deep: [/blue$/],
      greedy: [/yellow$/]
    }
})

Dans cet exemple, les sélecteurs se terminant par red comme .bg-red, les sélecteurs se terminant par blue ainsi que leurs enfants comme blue p ou .bg-blue .child-of-bg, et les sélecteurs dont une partie se termine par yellow comme button.bg-yellow.other-class, seront conservés dans le CSS final.

Les motifs sont des expressions régulières. Vous pouvez utiliser regexr pour vérifier que les expressions régulières correspondent à ce que vous recherchez.

Si votre configuration ne peut pas contenir d'expressions régulières, par exemple un fichier JSON comme postcss.config.json, écrivez l'expression régulière sous forme de chaîne de caractères entre barres obliques. Les drapeaux se placent après la dernière barre oblique. Toute autre chaîne de caractères correspond toujours exactement à un sélecteur.

{
  "safelist": {
    "standard": ["/red$/", "/^btn-/i", "active"],
    "deep": ["/blue$/"],
    "greedy": ["/yellow$/"]
  }
}

Les chaînes entre barres obliques fonctionnent dans toutes les options qui acceptent des expressions régulières : safelist, blocklist et dynamicAttributes.

Directement dans le CSS

Vous pouvez ajouter des éléments à la safelist directement dans votre CSS avec un commentaire spécial. Utilisez /* purgecss ignore */ pour ajouter la règle suivante à la safelist.

/* purgecss ignore */
h1 {
    color: blue;
}

Utilisez /* purgecss ignore current */ pour ajouter la règle actuelle à la safelist.

h1 {
    /* purgecss ignore current */
    color: blue;
}

Vous pouvez utiliser /* purgecss start ignore */ et /* purgecss end ignore */ pour ajouter une plage de règles à la safelist.

/* purgecss start ignore */
h1 {
  color: blue;
}

h3 {
  color: green;
}
/* purgecss end ignore */

h4 {
  color: purple;
}

/* purgecss start ignore */
h5 {
  color: pink;
}

h6 {
  color: lightcoral;
}

/* purgecss end ignore */

Lorsque les options keyframes, fontFace ou variables sont activées, les règles @keyframes, @font-face et @property ajoutées à la safelist par ces commentaires ne sont pas supprimées, pas plus que les keyframes, polices et variables CSS utilisées par les règles de la safelist.

Points d'attention

Certains outils d'optimisation CSS tels que PostCSS ou cssnano suppriment les commentaires avant que PurgeCSS ne s'exécute dans votre processus de build. Cela peut passer inaperçu car ces étapes sont souvent désactivées en développement. Pour éviter que ces commentaires soient supprimés, vous pouvez les marquer comme importants avec un point d'exclamation.

/*! purgecss start ignore */
h5 {
  color: pink;
}

h6 {
  color: lightcoral;
}

/*! purgecss end ignore */