31 de marzo de 2025·1 min de lectura

Actualiza Tu Sitio Hugo a Tailwind CSS v4

Guía paso a paso para migrar un sitio Hugo de Tailwind CSS v3 a v4 con la nueva configuración CSS-first.

Hay una nueva versión mayor de Tailwind CSS que incluye varios cambios. Así es como actualizar un sitio Hugo de Tailwind CSS v3 a v4 y optimizar el proceso de build.

Importante: Haz una copia de seguridad completa de tu proyecto o crea una nueva rama antes de empezar.

1. Actualizar el paquete de Tailwind

Usa la herramienta de actualización de Tailwind desde un proyecto v3:

npx @tailwindcss/upgrade

Esto actualiza package.json a Tailwind CSS v4 y convierte tu archivo CSS principal al nuevo formato de imports.

Si tu CSS importa tailwind.config.js, elimina esa línea y adapta al nuevo formato de configuración.

2. Cambiar los Pipes de Hugo

Reemplaza los pipes de PostCSS con @tailwindcss/cli y el nuevo pipe css.TailwindCSS de Hugo.

2.1. Instalar el CLI de Tailwind CSS

npm install -D @tailwindcss/cli

Crea un nuevo partial css.html en layouts/partials/:

{{ with (templates.Defer (dict "key" "global")) }}
  {{ with resources.Get "css/styles.css" }}
    {{ $opts := dict "minify" hugo.IsProduction "inlineImports" true }}
    {{ with . | css.TailwindCSS $opts }}
      {{ if hugo.IsProduction }}
        {{ with . | fingerprint }}
          <link
            rel="stylesheet"
            href="{{ .RelPermalink }}"
            integrity="{{ .Data.Integrity }}"
            crossorigin="anonymous"
          />
        {{ end }}
      {{ else }}
        <link rel="stylesheet" href="{{ .RelPermalink }}" />
      {{ end }}
    {{ end }}
  {{ end }}
{{ end }}

2.2. Actualizar tu CSS

Cambia la ruta de css/styles.css para que apunte a tu carpeta de assets. Luego usa este partial en tu head:

<head>
  <meta charset="utf-8" />
  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
  <meta author="Author Name" />
  <meta name="description" content="{{ .Description }}">
  <title>{{ .Site.Title }}</title>
  {{ partial "head/css.html" . }}
</head>

3. Configuración de Hugo

Añade esta configuración de build y módulos a tu config de Hugo:

[build]
  [build.buildStats]
    enable = true
  [[build.cachebusters]]
    source = 'assets/notwatching/hugo_stats\.json'
    target = 'css'
  [[build.cachebusters]]
    source = '(postcss|tailwind)\.config\.js'
    target = 'css'
[module]
  [[module.mounts]]
    source = 'assets'
    target = 'assets'
  [[module.mounts]]
    disableWatch = true
    source = 'hugo_stats.json'
    target = 'assets/notwatching/hugo_stats.json'

4. Actualizar Plugins

Si usas plugins como @tailwindcss/typography o DaisyUI, actualízalos a la última versión:

@plugin "@tailwindcss/typography";

5. CSS Final

Después de la actualización, tu archivo CSS debería verse así:

@import "tailwindcss";

@source 'hugo_stats.json';

@plugin "daisyui" {
  themes:
    light --default,
    dracula --prefersdark;
}

@plugin "@tailwindcss/typography";

@theme {
  --font-ubuntu: ubuntu-regular;
}

@layer base {
  *,
  ::after,
  ::before,
  ::backdrop,
  ::file-selector-button {
    border-color: var(--color-gray-200, currentColor);
  }
}

Ahora puedes eliminar de forma segura los paquetes postcss y autoprefixer.

Etiquetas:#hugo#tailwindcss#css