Scrivere un plugin Tailwind

In Tailwind CSS 4 un plugin personalizzato si scrive con @utility nel CSS; il plugin JavaScript serve solo quando devi distribuirlo come pacchetto.

La via breve: @utility

@import "tailwindcss";

@utility content-auto {
  content-visibility: auto;
  contain-intrinsic-size: 1px 500px;
}

L'utility finisce nel layer utilities e accetta le varianti: hover:content-auto, lg:content-auto. Non serve JavaScript, non serve tailwind.config.js e non serve un pacchetto.

Utility con un valore

Una utility funzionale riceve un argomento tramite --value():

@theme {
  --tab-size-github: 8;
}

@utility tab-* {
  tab-size: --value(--tab-size-*, integer, [integer]);
}

Così funzionano tab-2, tab-76, tab-github e tab-[3]. --value() legge chiavi del tema, valori nudi e valori arbitrari; le dichiarazioni che non risolvono vengono omesse dall'output.

Quando serve un plugin JavaScript

Un plugin JavaScript resta utile se pubblichi utility per altri progetti. Si scrive con l'helper plugin():

import plugin from "tailwindcss/plugin";

export default plugin(({ addUtilities, addVariant }) => {
  addUtilities({
    ".content-auto": { "content-visibility": "auto" },
  });
  addVariant("hocus", ["&:hover", "&:focus-visible"]);
});

Si carica con la direttiva @plugin, che accetta un nome di pacchetto o un percorso locale. Le API stabili sono addUtilities, addComponents e addVariant.

@import "tailwindcss";
@plugin "./hocus-plugin.js";

Le opzioni corePlugins e safelist della configurazione JavaScript non sono supportate in 4. Al posto della safelist c'è @source inline().

La limitazione

Un plugin JavaScript è codice tuo: ha un nome, una versione e un test da mantenere, e le utility che genera non esistono nel progetto finché qualcuno non lo carica. In cambio non è tipizzato e un selettore sbagliato fallisce in silenzio. Per due utility interne @utility costa meno e resta nello stesso file.

Dove continuare

Nel catalogo: i componenti Tailwind, la libreria tailwind-admin e le sezioni hero, tutte costruite con utility. Il framework è spiegato in che cos'è Tailwind CSS, le classi mancanti in content paths; per scegliere una libreria leggi le migliori librerie Tailwind e il confronto Tailwind contro CSS Modules.