@astrojs/ tailwind

v5.1.2 GitHub npm Changelog

Diese Astro-Integration erlaubt dir, Tailwinds CSS-Hilfsklassen in jeder .astro-Datei und UI-Framework-Komponente deines Projekts zu verwenden.

Warum Tailwind?

Tailwind ermöglicht es dir, Hilfsklassen anstelle von CSS zu verwenden. Diese Hilfsklassen entsprechen größtenteils einer bestimmten CSS-Eigenschaftseinstellung: Zum Beispiel entspricht das Hinzufügen von text-lg zu einem Element dem Setzen von font-size: 1.125rem in CSS. Du findest es möglicherweise einfacher, deine Styles mithilfe dieser vordefinierten Hilfsklassen zu schreiben und zu pflegen!

Wenn dir diese vordefinierten Einstellungen nicht gefallen, kannst du die Tailwind-Konfigurationsdatei den Designanforderungen deines Projekts anpassen. Wenn zum Beispiel der “große Text” in deinem Design tatsächlich 2rem beträgt, kannst du die lg fontSize-Einstellung auf 2rem ändern.

Tailwind ist auch eine großartige Wahl, um Styles zu React-, Preact- oder Solid-Komponenten hinzuzufügen, die keinen <style>-Tag in der Komponentendatei unterstützen.

Hinweis: Es wird im Allgemeinen davon abgeraten, sowohl Tailwind als auch eine andere Styling-Methode (z. B. Styled Components) in derselben Datei zu verwenden.

Installation

Astro verfügt über einen astro add-Befehl, der das Setup offizieller Integrationen automatisiert. Wenn du möchtest, kannst du die Integrationen auch manuell installieren.

Führe einen der folgenden Befehle in einem neuen Terminal-Fenster aus.

npx astro add tailwind

pnpm astro add tailwind

yarn astro add tailwind

Sollten dir dabei Probleme begegnen, melde sie gerne bei uns auf GitHub und versuche stattdessen die manuelle Installation.

Manuelle Installation

Installiere als Erstes die @astrojs/tailwind und tailwindcss-Pakete mit dem Paketemanager deiner Wahl.

npm install @astrojs/tailwind tailwindcss

pnpm add @astrojs/tailwind tailwindcss

yarn add @astrojs/tailwind tailwindcss

Füge die Integration dann deiner Astro-Konfigurationsdatei hinzu, indem du die integrations-Eigenschaft benutzt:

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

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

Erstelle als Nächstes eine tailwind.config.mjs-Datei in deinem Projektstammverzeichnis. Du kannst folgenden Befehl ausführen, um eine Konfigurationsdatei mit Basiseinstellungen für dich erstellen zu lassen:

npx tailwindcss init

pnpm dlx tailwindcss init

yarn dlx tailwindcss init

Zum Schluss, füge diese Basiskonfiguration in deiner tailwind.config.mjs-Datei ein:

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

Anwendung

Wenn du diese Integration installierst, kannst du die Hilfsklassen von Tailwind sofort verwenden. Gehe zur Tailwind-Dokumentation, um zu lernen, wie man Tailwind verwendet. Wenn du eine Hilfsklasse findest, die du ausprobieren möchtest, füge sie einfach einem HTML-Element in einem Projekt hinzu!

Autoprefixer wird auch automatisch eingerichtet, wenn du im Entwicklungsmodus arbeitest; aber auch in Production-Builds, sodass Tailwind-Klassen in älteren Browsern funktionieren.

Konfiguration

Tailwind konfigurieren

Wenn du die automatische Installation verwendet und jede Aufforderung mit Ja beantwortet hast, siehst du in deinem Projektstammverzeichnis eine tailwind.config.mjs-Datei. In dieser Datei kannst du Änderungen an deiner Tailwind-Konfiguration vornehmen. Du kannst in der Tailwind-Dokumentation lernen, wie man Tailwind konfiguriert.

Wenn du keine Konfigurationsdatei findest, füge deine eigene tailwind.config.(js|cjs|mjs|ts|mts|cts)-Datei dem Projektstammverzeichnis hinzu und die Integration wird sie verwenden. Dies kann hilfreich sein, wenn du Tailwind bereits in einem anderen Projekt konfiguriert hast und dessen Einstellungen auf das neue Projekt übertragen möchtest.

Die Integration konfigurieren

Die Astro-Tailwind-Integration kümmert sich um die Kommunikation zwischen Astro und Tailwind und verfügt über eigene Konfigurationsoptionen. Ändere diese in der astro.config.mjs-Datei (nicht in der Tailwind-Konfigurationsdatei), wo die Einstellungen der Integrationen deines Projekts zu finden sind.

configFile

Früher bekannt als config.path in @astrojs/tailwind v3. Sieh dir das v4 Änderungsprotokoll an, um deine Konfiguration zu aktualisieren.

Wenn du eine andere Tailwind-Konfigurationsdatei als die übliche tailwind.config.(js|cjs|mjs|ts|mts|cts)-Datei verwenden möchtest, musst du den Ort dieser Datei in der configFile-Option der Integration angeben. Wenn du einen relativen Pfad verwendest, wird der Pfad relativ zum aktuellen Arbeitsverzeichnis berechnet.

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

export default defineConfig({
  // ...
  integrations: [
    tailwind({
      // Beispiel: Füge den relative Pfad zur Tailwind Konfigurationsdatei hinzu
      configFile: './custom-config.mjs',
    }),
  ],
});

applyBaseStyles

Früher bekannt als config.applyBaseStyles in @astrojs/tailwind v3. Sieh dir das v4 Änderungsprotokoll an, um deine Konfiguration zu aktualisieren.

Standardmäßig importiert die Integration eine einfache base.css-Datei auf jeder Seite deines Projekts. Diese grundlegende CSS-Datei enthält die drei wichtigsten @tailwind-Direktiven:

/* Die standardmäßig eingefügte base.css Datei der Integration */
@tailwind base;
@tailwind components;
@tailwind utilities;

Um dieses Standardverhalten zu deaktivieren, setze applyBaseStyles auf false. Dies kann hilfreich sein, wenn du deine eigene base.css-Datei definieren musst (zum Beispiel um die @layer-Direktive zu verwenden). Nützlich ist das auch, wenn du nicht willst, dass base.css in jeder Seite deines Projekts importiert wird.

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

export default defineConfig({
  // ...
  integrations: [
    tailwind({
      // Beispiel: Deaktiviere das Einfügen eines grundlegenden
      // `base.css`-Imports auf jeder Seite.
      // Nützlich, wenn du deine eigene benutzerdefinierte `base.css`
      // definieren und/oder importieren musst.
      applyBaseStyles: false,
    }),
  ],
});

Du kannst jetzt deine eigene base.css-Datei als lokales Stylesheet importieren.

nesting

Setze auf true, um das tailwindcss/nesting-PostCSS-Plugin zu verwenden. So kannst du auch verschachtelte CSS-Deklarationen neben dem Tailwind-Syntax verwenden. Diese Option ist standardmäßig auf false gesetzt.

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

export default defineConfig({
  integrations: [
    tailwind({
      // Beispiel: Erlaubt das Verwenden verschachtelter CSS Deklarationen
      // neben dem Tailwind Syntax
      nesting: true,
    }),
  ],
});

Beispiele

Mit dem Astro Tailwind Starter kannst mit einer Basis für dein Projekt loslegen, die Tailwind für das Styling verwendet
Astros Homepage verwendet Tailwind. Schau dir die verwendete Tailwind-Konfigurationsdatei oder eine Beispielkomponente an
Die Astro Ink, Sarissa Blog, und Creek Designvorlagen verwenden Tailwind für das Styling
Für mehr Beispiele, suche nach Astro-Tailwind-Projekten auf GitHub!

Fehlerbehebung

Klasse existiert nicht mit `@apply`-Direktive

Wenn du die @apply-Direktive in dem <style>-Tag einer Astro-, Vue-, Svelte- oder anderen Komponente verwendest, kann es zu der Fehlermeldung kommen, dass die Tailwind-Klasse nicht existiert und der Build schlägt fehl.

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

Statt die @layer-Direktive in deinem globalen Stylesheet zu verwenden, füge deine eigenen Styles als Plugin in der Tailwind-Konfiguration hinzu, um den Fehler zu beheben:

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

Klassenbasierte Modifikatoren funkionieren nicht mit der `@apply`-Direktive

Bestimmte Tailwind-Klassen mit Modifikatoren basieren auf der Kombination von Klassen über mehrere Elemente hinweg. Beispielsweise wird group-hover:text-gray zu .group:hover .text-gray kompiliert. Wenn dies mit der @apply-Direktive in Astro-<style>-Tags verwendet wird, werden die kompilierten Styles aus dem Build entfernt, da sie mit keinem Markup in der .astro-Datei übereinstimmen. Das gleiche Problem kann auch bei Framework-Komponenten auftreten, die bereichsbezogene Styles unterstützen, wie etwa Vue und Svelte.

Um das zu beheben, kannst du die Klassen stattdessen inline verwenden:

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

Anderes

Wenn deine Installation scheinbar nicht funktioniert, versuche den Dev-Server neu zu starten.
Wenn du eine Seite bearbeitest und speicherst und die Seite sich nicht dementsprechend ändert, lade die Seite neu.
Wenn das Aktualisieren der Seite deine Vorschau nicht aktualisiert oder eine Neuinstallation nicht zu funktionieren scheint, starte den Entwicklungsserver neu.

Für weitere Hilfe, komme zu uns in den #support-Kanal auf Discord. Unsere freundlichen Support-Squad-Mitglieder helfen dir gerne!

Weitere Informationen zu Integrationen findest du in der Astro-Integrationen-Dokumentation.