Aller au contenu
Astro Astro

@astrojs/tailwind

Cette integration Astro apporte les classes CSS utilitaires de Tailwind aux fichiers .astro et aux composants de framework de votre projet, ainsi que le support du fichier de configuration de Tailwind.

Pourquoi Tailwind?

Tailwind vous permet d’utiliser des classes utilitaires au lieu d’écrire du CSS. Ces classes utilitaires sont pour la plupart identiques à certaines propriétés CSS : par exemple, ajouter le text-lg à un élément équivaut à définir font-size : 1.125rem en CSS. Vous trouverez peut-être plus facile d’écrire et de maintenir vos styles en utilisant ces classes utilitaires prédéfinies !

Si vous n’aimez pas ces paramètres prédéfinis, vous pouvez personnaliser le fichier de configuration de Tailwind en fonction des besoins de votre projet. Par exemple, si le “grand texte” de votre projet est en fait du 2rem, vous pouvez changer le paramètre lg fontSize en 2rem.

Tailwind est également un excellent choix pour ajouter des styles aux composants React, Preact ou Solid, qui ne supportent pas la balise <style> dans le fichier du composant.

Note: il est généralement déconseillé d’utiliser à la fois Tailwind et une autre méthode de stylisation (par exemple, Styled Components) dans le même fichier.

Installation

Installation Rapide

L’outil en ligne de commande astro add automatise l’installation pour vous. Exécutez l’une des commandes suivantes dans une nouvelle fenêtre de terminal. (Si vous n’êtes pas sûr du gestionnaire de paquets que vous utilisez, exécutez la première commande). Ensuite, suivez les invites, et tapez “y” dans le terminal (ce qui signifie “oui”) pour chacune d’entre elles.

Terminal window
# Si vous utilisez NPM
npx astro add tailwind
# Si vous utilisez Yarn
yarn astro add tailwind
# Si vous utilisez PNPM
pnpm astro add tailwind

Si vous rencontrez des problèmes, n’hésitez pas à nous les signaler sur GitHub et à essayer les étapes d’installation manuelle ci-dessous.

Installation manuelle

Tout d’abord, installez les paquets @astrojs/tailwind et tailwindcss en utilisant votre gestionnaire de paquets. Si vous utilisez npm ou si vous n’êtes pas sûr, lancez ceci dans le terminal :

Terminal window
npm install @astrojs/tailwind tailwindcss

Ensuite, appliquez cette intégration à votre fichier astro.config.* en utilisant la propriété integrations :

astro.config.mjs
import { defineConfig } from 'astro/config';
import tailwind from '@astrojs/tailwind';


export default defineConfig({
  // ...
  integrations: [tailwind()],
  //             ^^^^^^^^^^
});

Ensuite, créez un fichier tailwind.config.cjs dans le répertoire racine de votre projet. Vous pouvez utiliser la commande suivante pour générer un fichier de configuration de base :

Terminal window
npx tailwindcss init

Enfin, ajoutez cette configuration de base à votre fichier tailwind.config.cjs :

tailwind.config.cjs
/** @type {import('tailwindcss').Config} */
module.exports = {
  content: ['./src/**/*.{astro,html,js,jsx,md,mdx,svelte,ts,tsx,vue}'],
  theme: {
    extend: {},
  },
  plugins: [],
};

Usage

Lorsque vous installez l’intégration, les classes utilitaires de Tailwind devraient être prêtes à l’emploi. Consultez la documentation de Tailwind pour apprendre à utiliser Tailwind, et si vous voyez une classe utilitaire que vous voulez essayer, ajoutez-la à n’importe quel élément HTML de votre projet !

Autoprefixer est également mis en place automatiquement lorsque l’on travaille en mode dev, et pour les builds de production, afin que les classes Tailwind fonctionnent dans les anciens navigateurs.

Configuration

Configurer Tailwind

Si vous avez utilisé les instructions d’installation rapide et que vous avez répondu oui à chaque question, vous verrez un fichier tailwind.config.mjs dans le répertoire racine de votre projet. Utilisez ce fichier pour modifier la configuration de Tailwind. Vous pouvez apprendre à personnaliser Tailwind en utilisant ce fichier dans la documentation de Tailwind.

S’il n’existe pas encore, vous pouvez ajoutez votre propre fichier tailwind.config.(js|cjs|mjs) dans le répertoire racine et l’intégration utilisera ses configurations. Cela peut être intéressant si vous avez déjà configuré Tailwind dans un autre projet et que vous souhaitez transférer ces paramètres dans celui-ci.

Configuration de l’Intégration

L’intégration Astro Tailwind gère la communication entre Astro et Tailwind et possède ses propres options. Modifiez-les dans le fichier astro.config.mjs (et non dans le fichier de configuration de Tailwind) qui contient les paramètres d’intégration de votre projet.

Fichier de configuration

Précédemment connu sous le nom de config.path dans @astrojs/tailwind v3. Voir le changelog v4 pour mettre à jour votre configuration.

Si vous souhaitez utiliser un fichier de configuration Tailwind différent au lieu du fichier par défaut tailwind.config.(js|cjs|mjs), spécifiez l’emplacement de ce fichier en utilisant l’option configFile de cette intégration. Si configFile est relatif, il sera résolu par rapport au répertoire de travail actuel.

astro.config.mjs
import { defineConfig } from 'astro/config';
import tailwind from '@astrojs/tailwind';


export default defineConfig({
  integrations: [
    tailwind({
      // Exemple : Fournir un chemin personnalisé vers un fichier de configuration Tailwind
      configFile: './custom-config.cjs',
    }),
  ],
});

applyBaseStyles

Précédemment connu sous le nom config.applyBaseStyles dans @astrojs/tailwind v3. Voir le changelog v4 pour mettre à jour votre configuration.

Par défaut, l’intégration importe un fichier base.css sur chaque page de votre projet. Ce fichier CSS de base comprend les trois principales directives @tailwind :

/* Le fichier base.css injecté par défaut de l'intégration */
@tailwind base;
@tailwind components;
@tailwind utilities;

Pour désactiver ce comportement par défaut, attribuez la valeur false à applyBaseStyles. Cela peut être utile si vous devez définir votre propre fichier base.css (pour inclure une directive @layer, par exemple). Cela peut également être utile si vous ne souhaitez pas que base.css soit importé sur chaque page de votre projet.

astro.config.mjs
import { defineConfig } from 'astro/config';


export default defineConfig({
  integrations: [
    tailwind({
      // Exemple : Désactiver l'injection d'un import `base.css` de base sur chaque page.
      // Utile si vous avez besoin de définir et/ou d'importer votre propre `base.css`.
      applyBaseStyles: false,
    }),
  ],
});

Vous pouvez désormais importer votre propre base.css en tant que feuille de style locale (EN).

Examples

Troubleshooting

La classe n’existe pas avec les directives @apply

Lorsque vous utilisez la directive @apply dans une balise <style> d’Astro, Vue, Svelte ou d’une autre intégration de composant, cela peut générer des erreurs à propos de votre classe Tailwind personnalisée qui n’existe pas et faire échouer votre construction.

Terminal window
error   The `text-special` class does not exist. If `text-special` is a custom class, make sure it is defined within a `@layer` directive.

Au lieu d’utiliser les directives @layer dans une feuille de style globale, éfinissez vos styles personnalisés en ajoutant un plugin à votre configuration Tailwind pour y remédier :

tailwind.config.mjs
export default {
  // ...
  plugins: [
    function ({ addComponents, theme }) {
      addComponents({
        '.btn': {
          padding: theme('spacing.4'),
          margin: 'auto',
        },
      });
    },
  ],
};

Les modificateurs basés sur les classes ne fonctionnent pas avec les directives @apply

Certaines classes Tailwind avec modificateurs reposent sur la combinaison de classes sur plusieurs éléments. Par exemple, group-hover:text-gray se compile en .group:hover .text-gray. Lorsque cela est utilisé avec la directive @apply dans les balises <style> Astro, les styles compilés sont supprimés lors de la compilation parce qu’ils ne correspondent à aucune balise dans le fichier .astro. Le même problème peut également se produire dans les composants du framework qui supportent les styles scopés comme Vue et Svelte.

Pour résoudre ce problème, vous pouvez utiliser des classes en ligne à la place :

<p class="text-black group-hover:text-gray">Astro</p>

Autres

  • Si votre installation ne semble pas fonctionner, essayez de redémarrer le serveur de développement.
  • Si vous modifiez et enregistrez un fichier et que votre site n’est pas mis à jour en conséquence, essayez d’actualiser la page.
  • Si l’actualisation de la page ne met pas à jour votre aperçu, ou si une nouvelle installation ne semble pas fonctionner, redémarrez le serveur de développement.

Pour obtenir de l’aide, consultez le canal #support du Discord. Nos sympathiques membres de l’équipe d’assistance sont là pour vous aider !

Vous pouvez également consulter notre Documentation d’Intégration Astro pour en savoir plus sur les intégrations.

Contribuer

Ce paquet est maintenu par l’équipe Astro’s Core. Vous êtes les bienvenus pour soumettre un problème ou un PR !

Changelog

Voir CHANGELOG.md pour l’historique des modifications apportées à cette intégration.

Autres

Framework d'interface utilisateur

Adaptateurs SSR

Autres