@astrojs/ tailwind

v5.1.2 GitHub npm Registro de cambios

Esta integración de Astro trae las clases de CSS de utilidad de Tailwind a cada archivo .astro y componente de framework en tu proyecto, junto con el soporte para el archivo de configuración de Tailwind.

¿Por qué Tailwind?

Tailwind te permite usar clases de utilidad en lugar de escribir CSS. Estas clases de utilidad son en su mayoría uno a uno, con un cierto ajuste de propiedad CSS: por ejemplo, agregar el text-lg a un elemento es equivalente a establecer font-size: 1.125rem en CSS. ¡Es posible que te resulte más fácil escribir y mantener tus estilos usando estas clases de utilidad predefinidas!

Si no te gusta esa configuración predeterminada, puedes personalizar el archivo de configuración de Tailwind según los requisitos de diseño de tu proyecto. Por ejemplo, si el “texto grande” en tu diseño es en realidad 2rem, puedes cambiar la configuración de lg fontSize a 2rem.

Tailwind es también una buena opción para agregar estilos a los componentes React, Preact o Solid, que no admiten una etiqueta <style> en el archivo del componente.

Nota: generalmente no se aconseja usar Tailwind y otro método de estilado (por ejemplo, Styled Components) en el mismo archivo.

Instalación

Astro incluye un comando astro add para automatizar la configuración de integraciones oficiales. Si lo prefieres, puedes instalar integraciones manualmente en su lugar.

Ejecuta uno de los siguientes comandos en una nueva ventana de tu terminal.

npx astro add tailwind

pnpm astro add tailwind

yarn astro add tailwind

Si tienes algún problema, no dudes en informarnos en GitHub y prueba los pasos de instalación manual a continuación.

Instalación Manual

Primero, instala los paquetes @astrojs/tailwind y tailwindcss usando tu administrador de paquetes. Si estás usando npm o no estás seguro, ejecuta esto en la terminal:

npm install @astrojs/tailwind tailwindcss

pnpm add @astrojs/tailwind tailwindcss

yarn add @astrojs/tailwind tailwindcss

Luego, aplica la integración a tu archivo astro.config.* usando la propiedad integrations:

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

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

Luego, crea un archivo tailwind.config.mjs en el directorio raíz de tu proyecto. Puedes usar el siguiente comando para generar un archivo de configuración básico para ti:

npx tailwindcss init

pnpm dlx tailwindcss init

yarn dlx tailwindcss init

Finalmente, agrega esta configuración básica a tu archivo tailwind.config.mjs:

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

Uso

Cuando instalas la integración, las clases de utilidad de Tailwind deberían estar listas para ser usadas de inmediato. Dirígete a la documentación de Tailwind para aprender a usar Tailwind, y si ves una clase de utilidad que quieres probar, ¡agrégalas a cualquier elemento HTML de tu proyecto!

Tambien Autoprefixer es configurado automáticamente cuando se trabaja en modo desarrollo y para construcciones de producción, por lo que las clases de Tailwind funcionarán en navegadores antiguos.

Configuración

Configurando Tailwind

Si has usado las instrucciones de instalación rápida y has dicho que sí a cada instrucción, verás un archivo tailwind.config.mjs en el directorio raíz de tu proyecto. Usa este archivo para cambiar la configuración de Tailwind. Puedes aprender a personalizar Tailwind usando este archivo en la documentación de Tailwind.

Si no está ahí, puedes agregar tu propio archivo tailwind.config.(js|cjs|mjs|ts|mts|cts) al directorio raíz y la integración usará sus configuraciones. Esto puede ser genial si ya tienes Tailwind configurado en otro proyecto y quieres traer esa configuración a este.

Configurando la Integración

La integración de Astro Tailwind maneja la comunicación entre Astro y Tailwind y tiene sus propias opciones. Cambia estas opciones en el archivo astro.config.mjs (no el archivo de configuración de Tailwind) donde se encuentran los ajustes de integración de tu proyecto.

configFile

Previamente conocido como config.path en @astrojs/tailwind v3. Consulta el registro de cambios de v4 para actualizar tu configuración.

Si deseas usar una configuración diferente de Tailwind en lugar de la predeterminada tailwind.config.(js|cjs|mjs|ts|mts|cts), especifica la ubicación de ese archivo usando la opción configFile de esta integración. Si configFile es relativo, se resolverá en relación con el directorio de trabajo actual.

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

export default defineConfig({
  // ...
  integrations: [
    tailwind({
    // Ejemplo: Proporciona una ruta personalizada a un archivo de configuración de Tailwind
    configFile:'./custom-config.mjs',
    }),
  ],
});

applyBaseStyles

Previamente conocido como config.applyBaseStyles en @astrojs/tailwind v3. Consulta el registro de cambios de v4 para actualizar tu configuración.

Por defecto, la integración importa un archivo básico base.css en cada página de tu proyecto. Este archivo CSS básico incluye las tres directivas principales @tailwind:

/* El archivo base.css inyectado por defecto de la integración */
@tailwind base;
@tailwind components;
@tailwind utilities;

Para deshabilitar este comportamiento predeterminado, establece applyBaseStyles en false. Esto puede ser útil si necesitas definir tu propio archivo base.css (para incluir una directiva @layer, por ejemplo). Esto también puede ser útil si no deseas que base.css se importe en cada página de tu proyecto.

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

export default defineConfig({
  // ...
  integrations: [
    tailwind({
    // Ejemplo: Deshabilita la inyección de una importación básica de `base.css` en cada página.
    // Muy útil si necesitas definir e/o importar tu propio `base.css` personalizado.
    applyBaseStyles: false,
    }),
  ],
});

Ahora puedes importar tu propio base.css como una hoja de estilo local.

anidando

Establece true para aplicar el plugin de tailwindcss/nesting con PostCSS plugin para que puedas escribir declaraciones CSS anidadas junto con la sintaxis de Tailwind. Esta opción es “falsa” por defecto.

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

export default defineConfig({
  // ...
  integrations: [
    tailwind({
      // Example: Permite escribir declaraciones CSS anidadas
      // junto con la sintaxis de Tailwind
      nesting: true,
    }),
  ],
});

Ejemplos

El Astro Tailwind Starter te ayuda a comenzar con una base para tu proyecto que usa Tailwind para el estilado
La página de Astro usa Tailwind. Consulta su archivo de configuración de Tailwind o un componente de ejemplo
Los temas Astro Ink, Sarissa Blog, Blog Tecnológico de Astro y Creek usan Tailwind para el estilado
¡Explora proyectos de Astro Tailwind en Github para más ejemplos!

Solución de problemas

Las clases no existen con las directivas `@apply`

Cuando se usa la directiva @apply en una etiqueta <style> de integración de Astro, Vue, Svelte u otro componente, puede generar errores sobre la clase personalizada de Tailwind que no existe y causar que su compilación falle.

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

En lugar de usar directivas @layer en una hoja de estilo global, define tus estilos personalizados agregando un complemento a tu configuración de Tailwind para arreglarlo:

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

Los modificadores basados en clases no funcionan con las directivas `@apply`

Ciertas clases de Tailwind con modificadores dependen de combinar clases en varios elementos. Por ejemplo, group-hover:text-gray se compila en .group:hover .text-gray. Cuando se usa con la directiva @apply en las etiquetas <style> de Astro, los estilos compilados se eliminan de la salida de compilación porque no coinciden con ningún marcado en el archivo .astro. También puede ocurrir el mismo problema en componentes de framework que admiten estilos con alcance local como Vue y Svelte.

Para arreglar esto, puedes usar clases en línea en su lugar:

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

Otros

Si tu instalación no parece estar funcionando, intenta reiniciar el servidor de desarrollo.
Si editas y guardas un archivo y no ves que tu sitio se actualice en consecuencia, intenta actualizar la página.
Si al refrescar la página no se actualiza tu vista previa, o si una nueva instalación no parece estar funcionando, reinicia el servidor de desarrollo.

Para obtener ayuda, consulta el canal #support en Discord. ¡Nuestros amables miembros del Equipo de Soporte están aquí para ayudarte!

También puedes consultar nuestra Documentación de Integración de Astro para obtener más información sobre las integraciones.