Guía

Migrar un grid de Bootstrap a Tailwind CSS

Llevar un layout del grid de Bootstrap a Tailwind lleva cinco pasos y, en su mayor parte, un solo comando. Esta guía cubre qué cambia, cómo se corresponden las clases y las pocas cosas que un script no puede hacer por ti.

La migración en cinco pasos

  1. Instala el plugin

    Instala tw-bootstrap-grid y regístralo en tu configuración de Tailwind. La guía de instalación tiene los fragmentos para Tailwind v3 y v4.

  2. Iguala los breakpoints de Bootstrap (opcional)

    Si quieres que los layouts cambien en los mismos anchos de antes, define las pantallas de Tailwind en 576, 768, 992, 1200 y 1400px. Mira los breakpoints más abajo.

  3. Renombra las clases

    Haz commit de tu trabajo y ejecuta el comando Perl de abajo. Renumera los gutters y convierte el col-md-6 de Bootstrap en md:col-6.

  4. Corrige lo que el comando no puede

    Cambia utilidades de espaciado como mb-3 por mb-4, sustituye las utilidades de display y flex de Bootstrap por las de Tailwind y reemplaza clases como container-md.

  5. Quita el CSS de Bootstrap y revisa el resultado

    Elimina la hoja de estilos de Bootstrap y revisa tus páginas en anchos de móvil, tableta y escritorio.

Qué cambia y qué no

  • Lo que no cambia

    La estructura: .container, .row, .col-*, .offset-*, .row-cols-*. Incluso las variables CSS mantienen su nombre, --bs-gutter-x y --bs-gutter-y, así que el CSS propio que las lee sigue funcionando.

  • Prefijo, no infijo

    Bootstrap escribe col-md-6. Tailwind escribe md:col-6. Es el cambio que más vas a tocar, y un script puede hacerlo por ti.

  • Números distintos

    Los números de gutter y de espaciado siguen la escala de Tailwind, así que el g-3 de Bootstrap es g-4 aquí. Los anchos de los breakpoints también difieren un poco.

El mismo layout, antes y después

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>

Equivalencia de clases

Clases responsive

Clases responsive
BootstrapAquíNotas
col-md-6md:col-6Tailwind pone el breakpoint delante, como prefijo.
col-lglg:colLo mismo para la columna de ancho igual.
col-xl-autoxl:col-auto
offset-md-3md:offset-3
row-cols-md-3md:row-cols-3
g-md-4md:g-6El número también cambia, mira los tamaños de gutter más abajo.
col-xxl-42xl:col-4El xxl de Bootstrap se llama 2xl en Tailwind.
order-md-2md:order-2order-* es de Tailwind y llega hasta 12.

Tamaños de gutter

Tamaños de gutter
BootstrapAquíTamaño
g-0g-00
g-1g-10.25rem
g-2g-20.5rem
g-3g-41rem
g-4g-61.5rem
g-5g-123rem

Utilidades que vienen de Tailwind

Utilidades que vienen de Tailwind
BootstrapAquíNotas
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-4Las utilidades de espaciado se desplazan igual que los gutters.

Iguala los breakpoints de Bootstrap

Los breakpoints de Bootstrap son 576, 768, 992, 1200 y 1400px. Los de Tailwind son 640, 768, 1024, 1280 y 1536px, así que tras migrar un layout puede cambiar un poco antes o después. Si eso importa, define las pantallas de Tailwind con los valores de 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 */
}

El container de Tailwind tiene el ancho del breakpoint en el que está, así que sus anchos máximos pasan a ser 576, 768, 992, 1200 y 1400px. Es parecido a los 540, 720, 960, 1140 y 1320px de Bootstrap, pero no idéntico.

Renombrar en bloque

Este comando Perl renumera los gutters y convierte col-md-6 en md:col-6, col-xxl-4 en 2xl:col-4 y el antiguo no-gutters en g-0. Reescribe los archivos en su sitio, así que haz commit antes y revisa el diff después.

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')

Ejecútalo una sola vez y revisa el resultado

Ejecutarlo una segunda vez volvería a renumerar los gutters. Además, solo conoce los nombres de clase de arriba, así que las utilidades de espaciado como mb-3 o p-3 necesitan una revisión manual, y el patrón coincide con cualquier texto que parezca una clase, incluso dentro de comentarios.

Lo que no se traslada

El plugin solo añade .container y .container-fluid, así que .container-sm, .container-md y los demás contenedores responsive de Bootstrap no están incluidos. Constrúyelos con las utilidades max-w-* de Tailwind si los necesitas. Las demás utilidades de Bootstrap (display, flex, espaciado, texto) las sustituyen las de Tailwind, como en la última tabla de arriba.

Sigue adelante