Guia

Migrando um grid do Bootstrap para o Tailwind CSS

Levar um layout do grid do Bootstrap para o Tailwind leva cinco passos e, na maior parte, um único comando. Este guia mostra o que muda, como as classes se correspondem e as poucas coisas que um script não consegue fazer por você.

Migração em cinco passos

  1. Instale o plugin

    Instale o tw-bootstrap-grid e registre-o na sua configuração do Tailwind. O guia de instalação tem os trechos para Tailwind v3 e v4.

  2. Iguale os breakpoints do Bootstrap (opcional)

    Se quiser que os layouts mudem nas mesmas larguras de antes, defina as telas do Tailwind como 576, 768, 992, 1200 e 1400px. Veja os breakpoints mais abaixo.

  3. Renomeie as classes

    Faça commit do seu trabalho e depois execute o comando Perl abaixo. Ele renumera os gutters e transforma o col-md-6 do Bootstrap em md:col-6.

  4. Corrija o que o comando não consegue

    Troque utilitárias de espaçamento como mb-3 por mb-4, substitua as utilitárias de display e flex do Bootstrap pelas do Tailwind e troque classes como container-md.

  5. Remova o CSS do Bootstrap e confira o resultado

    Tire a folha de estilos do Bootstrap e depois percorra suas páginas em larguras de celular, tablet e desktop.

O que muda e o que não muda

  • O que continua igual

    A estrutura: .container, .row, .col-*, .offset-*, .row-cols-*. Até as variáveis CSS mantêm os nomes, --bs-gutter-x e --bs-gutter-y, então o CSS próprio que as lê continua funcionando.

  • Prefixo, não infixo

    O Bootstrap escreve col-md-6. O Tailwind escreve md:col-6. É a mudança que você mais vai tocar, e um script pode fazê-la por você.

  • Números diferentes

    Os números de gutter e de espaçamento seguem a escala do Tailwind, então o g-3 do Bootstrap é g-4 aqui. As larguras dos breakpoints também diferem um pouco.

O mesmo layout, antes e depois

Bootstrap 5

index.html
<div class="container">
  <div class="row g-3">
    <div class="col-12 col-md-6 col-lg-4">A</div>
    <div class="col-12 col-md-6 col-lg-4">B</div>
    <div class="col-12 col-md-12 col-lg-4">C</div>
  </div>
</div>

tw-bootstrap-grid

index.html
<div class="container">
  <div class="row g-4">
    <div class="col-12 md:col-6 lg:col-4">A</div>
    <div class="col-12 md:col-6 lg:col-4">B</div>
    <div class="col-12 md:col-12 lg:col-4">C</div>
  </div>
</div>

Equivalência de classes

Classes responsivas

Classes responsivas
BootstrapAquiObservações
col-md-6md:col-6O Tailwind coloca o breakpoint na frente, como prefixo.
col-lglg:colO mesmo vale para a coluna de largura igual.
col-xl-autoxl:col-auto
offset-md-3md:offset-3
row-cols-md-3md:row-cols-3
g-md-4md:g-6O número também muda, veja os tamanhos de gutter abaixo.
col-xxl-42xl:col-4O xxl do Bootstrap se chama 2xl no Tailwind.
order-md-2md:order-2order-* é do Tailwind e vai até 12.

Tamanhos de gutter

Tamanhos de gutter
BootstrapAquiTamanho
g-0g-00
g-1g-10.25rem
g-2g-20.5rem
g-3g-41rem
g-4g-61.5rem
g-5g-123rem

Utilitárias que vêm do Tailwind

Utilitárias que vêm do Tailwind
BootstrapAquiObservações
d-flexflex
d-none d-md-blockhidden md:block
justify-content-betweenjustify-between
align-items-centeritems-center
align-self-endself-end
mb-3, p-3mb-4, p-4As utilitárias de espaçamento mudam do mesmo jeito que os gutters.

Iguale os breakpoints do Bootstrap

Os breakpoints do Bootstrap são 576, 768, 992, 1200 e 1400px. Os do Tailwind são 640, 768, 1024, 1280 e 1536px, então um layout pode mudar um pouco antes ou depois após a migração. Se isso importa, defina as telas do Tailwind com os valores do Bootstrap.

Tailwind v4

main.css
@import "tailwindcss";
@plugin "tw-bootstrap-grid";

@theme {
  --breakpoint-sm: 36rem;    /* 576px */
  --breakpoint-md: 48rem;    /* 768px */
  --breakpoint-lg: 62rem;    /* 992px */
  --breakpoint-xl: 75rem;    /* 1200px */
  --breakpoint-2xl: 87.5rem; /* 1400px */
}

O container do Tailwind tem a largura do breakpoint em que está, então suas larguras máximas passam a ser 576, 768, 992, 1200 e 1400px. É parecido com os 540, 720, 960, 1140 e 1320px do Bootstrap, mas não idêntico.

Renomear em massa

Este comando Perl renumera os gutters e transforma col-md-6 em md:col-6, col-xxl-4 em 2xl:col-4 e o antigo no-gutters em g-0. Ele reescreve os arquivos no lugar, então faça commit antes e leia o diff depois.

terminal
perl -pi -e '
  s/\b(g|gx|gy)-((?:sm|md|lg|xl|xxl)-)?([345])\b/"$1-".($2\/\/"").{3=>4,4=>6,5=>12}->{$3}/ge;
  s/\bno-gutters\b/g-0/g;
  s/\b(col|offset|order|row-cols|g|gx|gy)-(sm|md|lg|xl|xxl)(-([0-9]+|auto|first|last))?\b/$2:$1$3/g;
  s/\bxxl:/2xl:/g;
' $(git ls-files '*.html' '*.jsx' '*.tsx' '*.vue' '*.svelte')

Execute uma vez e confira o resultado

Executá-lo uma segunda vez renumeraria os gutters de novo. Ele também só conhece os nomes de classe acima, então utilitárias de espaçamento como mb-3 ou p-3 precisam de uma revisão manual, e o padrão casa com qualquer texto que pareça uma classe, inclusive dentro de comentários.

O que não é migrado

O plugin só adiciona .container e .container-fluid, então .container-sm, .container-md e os outros contêineres responsivos do Bootstrap não estão incluídos. Monte-os com as utilitárias max-w-* do Tailwind se precisar. As outras utilitárias do Bootstrap (display, flex, espaçamento, texto) são substituídas pelas do Tailwind, como na última tabela acima.

Continue