@astrojs/ tailwind

v5.1.2 GitHub npm Journal des modifications

Cette intégration Astro apporte les classes CSS utilitaires de Tailwind à chaque fichier .astro et composant 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 exigences de conception 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 style (par exemple Styled Components) dans le même fichier.

Installation

Astro inclut une commande astro add pour automatiser l’installation des intégrations officielles. Si vous préférez, vous pouvez installer les intégrations manuellement à la place.

Exécutez l’une des commandes suivantes dans une nouvelle fenêtre de terminal.

npx astro add tailwind

pnpm astro add tailwind

yarn astro add tailwind

Si vous rencontrez des problèmes, n’hésitez pas à nous les signaler sur GitHub et essayez 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.

npm install @astrojs/tailwind tailwindcss

pnpm add @astrojs/tailwind tailwindcss

yarn add @astrojs/tailwind tailwindcss

Ensuite, appliquez l’intégration à votre fichier de configuration Astro en utilisant la propriété integrations :

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

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

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

npx tailwindcss init

pnpm dlx tailwindcss init

yarn dlx tailwindcss init

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

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

Utilisation

Lorsque vous installez l’intégration, les classes utilitaires de Tailwind devraient être prêtes à l’emploi. Rendez-vous sur le site Tailwind docs 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 !

Le Autoprefixer est également configuré automatiquement lorsque vous travaillez en mode dev, et pour les builds de production, de sorte que les classes Tailwind fonctionneront dans les anciens navigateurs.

Configuration

Configuration de 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 vos changements de configuration de Tailwind. Vous pouvez apprendre à personnaliser Tailwind en utilisant ce fichier dans la documentation de Tailwind.

S’il n’est pas là, vous ajoutez votre propre fichier tailwind.config.(js|cjs|mjs|ts|mts|cts) 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 (pas le fichier de configuration de Tailwind) qui est l’endroit où se trouvent les paramètres d’intégration de votre projet.

configFile

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 voulez utiliser un fichier de configuration Tailwind différent au lieu du fichier par défaut tailwind.config.(js|cjs|mjs|ts|mts|cts), 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 courant.

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.mjs',
    }),
  ],
});

applyBaseStyles

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

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

/* The integration's default injected base.css file */
@tailwind base;
@tailwind components;
@tailwind utilities;

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

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

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 maintenant importer votre propre base.css comme feuille de style locale.

nesting

Mettez true pour appliquer le tailwindcss/nesting PostCSS plugin afin que vous puissiez écrire des déclarations CSS imbriquées avec la syntaxe de Tailwind. Cette option est false par défaut.

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

export default defineConfig({
  integrations: [
    tailwind({
      // Exemple : Permettre l'écriture de déclarations CSS imbriquées
      // à côté de la syntaxe de Tailwind
      nesting: true,
    }),
  ],
});

Exemples

Astro Tailwind Starter vous permet de démarrer votre projet en utilisant Tailwind pour le stylisme.
La page d’accueil d’Astro utilise Tailwind. Consultez son fichier de configuration Tailwind ou un composant d’exemple.
Les thèmes Astro Ink, Sarissa Blog, Astro Tech Blog et Creek utilisent Tailwind pour le style.
Parcourir les projets Astro Tailwind sur GitHub pour plus d’exemples !

Dépannage

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 build.

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, définissez vos propres styles en ajoutant un plugin à votre configuration Tailwind pour résoudre ce problème :

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 des modificateurs reposent sur la combinaison de classes à travers 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 Astro <style>, les styles compilés sont supprimés de la sortie de la compilation parce qu’ils ne correspondent à aucune balise dans le fichier .astro. Le même problème peut 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 de rafraîchir 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 sur 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 plus d’informations sur les intégrations.