@astrojs/ tailwind

v5.1.0 GitHub npm Changelog

Esta integração Astro traz as classes CSS utilitárias do Tailwind para todos os arquivos .astro e componentes de framework em seu projeto, juntamente com suporte para o arquivo de configuração do Tailwind.

Por que Tailwind?

O Tailwind permite que você use classes de utilitário em vez de escrever CSS. Essas classes de utilitário são na maioria das vezes equivalentes a uma determinada configuração de propriedade CSS: por exemplo, adicionar text-lg a um elemento é equivalente a definir font-size: 1.125rem em CSS. Você pode achar mais fácil escrever e manter seus estilos usando essas classes de utilitário predefinidas!

Se você não gostar dessas configurações predefinidas, pode personalizar o arquivo de configuração do Tailwind de acordo com os requisitos de design do seu projeto. Por exemplo, se o “texto maior” em seu design for na verdade 2rem, você pode alterar a propriedade fontSize de lg para 2rem.

O Tailwind também é uma ótima escolha para adicionar estilos a componentes React, Preact ou Solid, que não suportam uma tag <style> no arquivo do componente.

Nota: geralmente não é recomendado usar tanto o Tailwind quanto outro método de estilização (por exemplo, Styled Components) no mesmo arquivo.

Instalação Rápida

O comando astro add automatiza a instalação para você. Execute um dos seguintes comandos em uma nova janela do terminal. (Se você não tem certeza de qual gerenciador de pacotes está usando, execute o primeiro comando.) Em seguida, siga as instruções e digite “y” no terminal (significando “sim”) para cada um.

# Usando NPM
npx astro add tailwind
# Usando Yarn
yarn astro add tailwind
# Usando PNPM
pnpm astro add tailwind

Se encontrar algum problema, sinta-se à vontade para relatar no GitHub e tente as etapas de instalação manual abaixo.

Instalação Manual

Primeiro, instale os pacotes @astrojs/tailwind e tailwindcss usando seu gerenciador de pacotes. Se você estiver usando npm ou não tiver certeza, execute isso no terminal:

npm install @astrojs/tailwind tailwindcss

Então, adicione essa integração em seu arquivo astro.config.* dentro da propriedade integrations:

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

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

Agora, crie o arquivo tailwind.config.cjs na raiz do seu projeto. Você pode usar o seguinte comando para criar uma configuração básica:

npx tailwindcss init

Finalmente, adicione essa configuração em seu arquivo tailwind.config.cjs:

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

Utilização

Quando instalar a integração, as classes utilitárias do Tailwind já devem estar prontas para uso. Acesse a documentação do Tailwind, para aprender como usá-lo corretamente, e se achar uma classe utilitária que deseja usar, adicione ela em qualquer elemento HTML em seu projeto!

O Autoprefixer é automaticamente adicionado quando estiver trabalhando no modo de desenvolvimento e em builds para produção, fazendo com que as classes do Tailwind funcionem em navegadores antigos.

Configuração

Configurando o Tailwind

Se você seguiu as instruções de Instalação Rápida e respondeu “sim” para todas, verá um arquivo tailwind.config.cjs na raiz do seu projeto. Use este arquivo para fazer alterações na configuração do Tailwind. Você pode aprender como personalizar o Tailwind utilizando esse arquivo na documentação oficial.

Se o arquivo não estiver lá, você pode adicionar seu próprio arquivo tailwind.config.(js|cjs|mjs) na raiz do projeto, e a integração usará suas configurações. Isso pode ser ótimo se você já configurou o Tailwind em outro projeto e deseja trazer essas configurações para este.

Configurando a Integração

A integração Astro Tailwind lida com a comunicação entre o Astro e o Tailwind e tem suas próprias opções. Altere essas opções no arquivo astro.config.mjs (não no arquivo de configuração do Tailwind), que é onde ficam as configurações de integração do seu projeto.

configFile

Anteriormente chamado de config.path no @astrojs/tailwind v3. Mais informações no histórico de mudanças da v4 para atualizar suas configurações.

Se você desejar usar um arquivo de configuração do Tailwind diferente do tailwind.config.(js|cjs|mjs) padrão, adicione a localização do arquivo usando a opção configFile da integração. Se o configFile é relativo, ele vai ser resolvido relativamente a partir do diretório de trabalho atual.

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

export default defineConfig({
  integrations: [
    tailwind({
      // Examplo: Adiciona uma caminho customizado para um arquivo de configuração Tailwind
      configFile: './custom-config.cjs',
    }),
  ],
});

applyBaseStyles

Anteriormente chamado de config.applyBaseStyles no @astrojs/tailwind v3. Veja mais no histórico de mudanças da v4 para atualizar sua configuração.

Por padrão, a integração importa um arquivo basico base.css em cada página do seu projeto. Esse arquivo CSS basico inclui as três diretivas principais do @tailwind:

/* O arquivo base.css injetado por padrão pela integração */
@tailwind base;
@tailwind components;
@tailwind utilities;

Para desabilitar esse comportamento padrão, configure o valor de applyBaseStyles para false. Isso pode ser útil em caso você deseje seu próprio arquivo base.css (para incluir a diretiva @layer, por exemplo). Além disso, outra utilidade é caso você não deseje que o arquivo base.css seja importado em cada página do seu projeto.

import { defineConfig } from 'astro/config';

export default defineConfig({
  integrations: [
    tailwind({
      // Exemplo: Desativa a injeção do arquivo básico `base.css` em cada página.
      // Útil se você precisa definir e/ou importar seu próprio arquivo `base.css` customizado.
      applyBaseStyles: false,
    }),
  ],
});

Você pode agora importar seu próprio base.css como um folha de estilos local.

Exemplos

O template Astro Tailwind Starter te ajuda a começar com uma base para o seu projeto que utiliza o Tailwind para estilização.
A página inicial do Astro utiliza o Tailwind. Confira seu arquivo de configuração do Tailwind ou um exemplo de componente.
Os temas Astro Ink, Sarissa Blog e Creek utilizam o Tailwind para estilização.
Navegue pelos projetos Astro Tailwind no GitHub para mais exemplos!

Solução de problemas

Classe não existe com diretivas `@apply`

Ao usar a diretiva @apply em um componente Astro, Vue, Svelte ou outra integração de componente dentro da tag <style>, ela pode gerar erros sobre a não existência da sua classe personalizada do Tailwind e fazer com que a build falhe.

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

Em vez de usar diretivas @layer em uma folha de estilo global, defina seus estilos personalizados adicionando um plugin ao seu arquivo de configuração do Tailwind para corrigir isso:

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

Modificadores baseados em classe não funcionam com diretivas `@apply`

Certas classes do Tailwind com modificadores dependem da combinação de classes em vários elementos. Por exemplo, group-hover:text-gray é compilado para .group:hover .text-gray. Quando isso é usado com a diretiva @apply em tags <style> do Astro, os estilos compilados são removidos da saída de compilação porque não correspondem a nenhuma marcação no arquivo .astro. O mesmo problema também pode ocorrer em componentes de framework que suportam estilos isolados, como Vue e Svelte.

Para corrigir isso, você pode usar classes incorporadas em vez disso:

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

Outros

Se a sua instalação não parecer estar funcionando, tente reiniciar o servidor de desenvolvimento.
Se você editar e salvar um arquivo e não ver o seu site atualizar de acordo, tente recarregar a página.
Se recarregar a página não atualizar a visualização, ou se uma nova instalação não parecer estar funcionando, reinicie o servidor de desenvolvimento.

Para obter ajuda, confira o canal #support no Discord. Os membros da nossa amigável equipe de suporte estão aqui para ajudar!

Você também pode conferir nossa Documentação de Integração do Astro para mais informações sobre integrações.

Contribuição

Este pacote é mantido pela equipe principal do Astro. Você é bem-vindo para enviar uma issue ou PR!