Pular para o conteúdo

@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?

Seção intitulada 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 (Vídeo legendado)

Seção intitulada Instalação (Vídeo legendado)

Instalação Rápida

Seção intitulada 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.

Terminal window
# 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

Seção intitulada 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:

Terminal window
npm install @astrojs/tailwind tailwindcss

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

astro.config.mjs
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:

Terminal window
npx tailwindcss init

Finalmente, adicione essa configuração em seu arquivo 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: [],
};

Utilização

Seção intitulada 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

Seção intitulada Configuração

Configurando o Tailwind

Seção intitulada 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

Seção intitulada 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

Seção intitulada 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.

astro.config.mjs
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

Seção intitulada 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.

astro.config.mjs
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

Seção intitulada Exemplos

Solução de problemas

Seção intitulada Solução de problemas

Classe não existe com diretivas @apply

Seção intitulada 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.

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.

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:

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

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

Seção intitulada 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ção intitulada 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

Seção intitulada Contribuição

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

Histórico de alterações

Seção intitulada Histórico de alterações

Veja CHANGELOG.md para ver o histórico de alterações desta integração.

Mais integrações

Frameworks de UI

Adaptadores de SSR

Outras integrações