Tailwind CSS v4: jak przejść z v3 i uniknąć problemów

Tailwind CSS v4 wprowadza konfigurację CSS-first, zmienia integracje z bundlerami i automatycznie wykrywa klasy w plikach projektu. W v3 arkusz zwykle zawierał dyrektywy `@tailwind`, a ścieżki szablonów deklarowało się w `content` pliku konfiguracyjnym. W v4 używa się `@import "tailwindcss"`, a tokeny motywu można deklarować przez `@theme`.

Tabela zestawia zmiany między wersjami i wskazuje, co trzeba sprawdzić w istniejącym projekcie.

Konfiguracja JavaScript nie jest automatycznie ładowana przez v4. Można podłączyć ją dyrektywą `@config`, ale część opcji, w tym `corePlugins`, `safelist` i `separator`, nie jest obsługiwana. Klasy, których nie ma w skanowanych plikach, można wskazać przez `@source inline()`.

Część utilities zmieniła nazwy lub wartości domyślne. Przykładowo `bg-opacity-*` zastępuje się modyfikatorem opacity w klasie koloru, `flex-shrink-*` zmienia się na `shrink-*`, a domyślna grubość klasy `ring` jest inna. Build może się udać, mimo że komponent wygląda inaczej, dlatego porównaj reprezentatywne widoki.

Tailwind CSS v4.0 wymaga Safari 16.4, Chrome 111 i Firefox 128 lub nowszych. Jeżeli projekt musi obsługiwać starsze wersje, dokumentacja Tailwind zaleca pozostanie przy v3.4 do czasu zmiany wymagań. Szczegółowy wykaz zmian zawiera oficjalny przewodnik migracji Tailwind CSS.

Projekt jest gotowy do migracji, gdy można odtworzyć build i wskazać miejsca, z których mają być wykrywane klasy. Przed zmianą zanotuj wersję Node.js, komendę produkcyjną, lockfile, konfigurację bundlera i widoki dostępne na stagingu. W motywie WordPress uwzględnij pliki PHP, bloki, partiale i katalogi wtyczek dostarczające markup z klasami Tailwind.

Tabela porządkuje dane, które warto zachować przed rozpoczęciem zmiany. Dzięki temu po migracji łatwiej porównać konfigurację i ustalić źródło regresji.

Własne pluginy i tokeny wymagają osobnego przeglądu, ponieważ migrator może nie odtworzyć ich logiki. Wyszukaj klasy dynamiczne, utilities opacity oraz style zapisane w `@layer components` lub `@layer utilities`. W v4 własne utilities rejestruje się dyrektywą `@utility`, a CSS korzysta z natywnych warstw kaskady.

Zapisz przed zmianą widoki reprezentatywne dla projektu: kategorię, produkt wariantowy, koszyk, checkout i komunikat walidacyjny. Jeśli motyw ma menu mobilne, filtry lub popup, uwzględnij ich stany otwarte i zamknięte. Wybór systemu treści warto powiązać z porównaniem WordPressa, Drupala i Joomli.

Migrację wykonaj na osobnym branchu, żeby móc przywrócić zależności, konfigurację CSS i lockfile jako spójny zestaw. Oficjalny upgrader automatyzuje większość zmian, ale jego wynik wymaga przeglądu.

1. Utwórz branch migracyjny i zapisz commit bazowy oraz aktualny build.
2. Sprawdź Node.js lokalnie i w CI; `npx @tailwindcss/upgrade` wymaga Node.js 20 lub nowszego.
3. Uruchom `npx @tailwindcss/upgrade` w katalogu projektu.
4. Przejrzyj zmiany zależności, konfiguracji, CSS i szablonów, ze szczególnym uwzględnieniem pluginów.
5. Uruchom komendę produkcyjną z `package.json` w środowisku zgodnym z CI.
6. Porównaj reprezentatywne widoki na stagingu z wersją v3.

W projekcie Vite Tailwind zaleca plugin `@tailwindcss/vite`. Dodaj `tailwindcss()` do `plugins` w `vite.config.*`, a w arkuszu wejściowym umieść `@import "tailwindcss";`. W projekcie PostCSS skonfiguruj `@tailwindcss/postcss` w `postcss.config.*`; sam pakiet `tailwindcss` nie pełni już funkcji pluginu PostCSS.

Jeśli nie używasz automatycznego upgradera, wykonuj zmianę etapami: zaktualizuj zależności, integrację bundlera i import CSS, następnie przenieś tokeny do `@theme` i uzupełnij źródła klas przez `@source`. Build po każdym etapie ułatwia odróżnienie błędów konfiguracji od różnic wizualnych.

Po zbudowaniu arkusza potwierdź, że motyw ładuje nowy asset. W DevTools otwórz kartę Network i sprawdź adres, status oraz zawartość pobranego CSS. Jeśli widzisz poprzednią wersję arkusza, sprawdź cache buildu, wtyczki optymalizującej i CDN.

W projektach WordPress zakres prac zależy od motywu, pipeline'u i liczby widoków do sprawdzenia. Jeśli potrzebujesz wykonawcy prac przy witrynie WordPress, poznaj ofertę tworzenia stron na WordPressie, a przed ustaleniem migracji zweryfikuj, czy dany zakres odpowiada potrzebom projektu.

Brak stylu po aktualizacji najczęściej oznacza, że Tailwind nie wygenerował reguły albo inny arkusz ją nadpisał. Tailwind v4 skanuje pliki jako zwykły tekst i wyszukuje pełne ciągi przypominające nazwy klas. Nie analizuje logiki PHP ani JavaScript, więc nie odczyta nazwy złożonej z fragmentów.

Tabela łączy objaw z miejscem diagnozy i poprawką. Sprawdź najpierw CSS wygenerowany przez build, a później kaskadę w DevTools.

Tailwind domyślnie pomija pliki z `.gitignore`, katalog `node_modules`, pliki binarne, CSS i lockfile. Bibliotekę z klasami można jawnie dodać, na przykład `@source "../node_modules/nazwa-paczki";`. Ścieżka jest liczona względem arkusza CSS. W monorepo bazę skanowania można określić przez `source("../src")` w imporcie Tailwind.

Klasa złożona w PHP przez połączenie fragmentów, na przykład `bg-`, nazwy koloru i `-600`, nie występuje w kodzie jako pełny token. Zastąp takie składanie mapą, w której każdy wariant zawiera kompletną klasę, na przykład `blue => bg-blue-600` i `red => bg-red-600`. Gdy nazwy pochodzą wyłącznie z bazy danych lub API, wskaż wymagane utilities przez `@source inline("...")`.

Brak selektora w arkuszu wskazuje na problem źródła lub nazwy klasy. Selektor obecny, ale przekreślony w DevTools, oznacza konflikt kaskady. Zasady skanowania i rejestrowania źródeł zawiera dokumentacja wykrywania klas Tailwind.

Po migracji przetestuj produkt, koszyk, checkout, menu mobilne i walidację na desktopie oraz telefonie. Błąd CSS może ukryć wybór wariantu, cenę lub komunikat błędnego pola, nawet jeśli strona główna wygląda poprawnie.

Tabela przedstawia przypadki testowe i warunek akceptacji każdego widoku. Przejdź je na stagingu po zbudowaniu arkusza produkcyjnego.

Testuj działanie komponentów, nie tylko ich statyczny wygląd. Zmień wariant produktu, liczbę sztuk w koszyku i wyślij niepełny formularz checkoutu. Otwórz menu na wąskim ekranie, sprawdź obsługę klawiaturą oraz komunikat po dodaniu produktu.

Wtyczki i buildery mogą generować markup poza katalogiem motywu. Jeśli ich klasy nie pojawiają się w CSS, dodaj odpowiednią ścieżkę przez `@source` albo zastąp dynamiczne składanie pełnymi nazwami. Uwzględnij stany pojawiające się po interakcji, ponieważ mogą być niewidoczne w pierwszym widoku strony.

Tailwind CSS v4 może współpracować z WordPressem, Vite i PostCSS, jeśli pipeline buduje arkusz v4 i skanuje właściwe źródła. WordPress dostarcza markup, a Tailwind kompiluje CSS w środowisku developerskim lub CI. Zgodność należy więc potwierdzić oddzielnie dla integracji i każdej wymaganej przeglądarki.

Tabela pokazuje pojedynczy warunek dla każdego składnika stosu. Wiersze przeglądarek rozdzielają wymagane wersje, aby można je było porównać z ruchem witryny.

Tailwind v4 importuje warstwy `theme`, `base`, `components` i `utilities`; Preflight zmienia podstawowe style elementów HTML. W istniejącym motywie reset może wpłynąć na wygląd komponentów wtyczek. Jeśli projekt nie powinien używać Preflight, można zaimportować wybrane części Tailwind i pominąć `preflight.css`.

Wstrzymaj aktualizację, jeśli nie można odtworzyć produkcyjnego buildu, źródła klas nie trafiają do CSS albo projekt musi obsługiwać przeglądarki starsze niż wymagane. Osobnej analizy wymaga plugin, którego konfiguracji migrator nie przenosi i którego nie da się zastąpić bez zmian w projekcie. Dokumentacja zgodności Tailwind CSS opisuje wymagania przeglądarek i ograniczenia narzędzi.

Rollback przywraca spójny zestaw zależności, lockfile, konfiguracji CSS i assetów z poprzedniej wersji. Cofnięcie samego arkusza przy pozostawieniu nowych pakietów może uniemożliwić odtworzenie buildu. Przed migracją zapisz commit bazowy, wersję Node.js i komendę wdrożeniową.

Gdy build lokalny lub CI kończy się błędem, zachowaj komunikat z pierwszej nieudanej operacji, wersję Node.js, manager pakietów i zmiany konfiguracji. Komunikat `Cannot find package '@tailwindcss/postcss'` wskazuje zwykle na brak zależności lub niezgodny wpis w PostCSS. Brak `@tailwindcss/vite` oznacza, że plugin nie jest dostępny w środowisku buildu.

Gdy build przechodzi, ale witryna nie ma stylów, sprawdź w DevTools kartę Network: kod odpowiedzi arkusza, jego adres i zawartość. Porównaj asset wdrożony na serwerze z wynikiem lokalnym, a następnie sprawdź cache aplikacji, wtyczki optymalizującej i CDN. Zapisz wersję pobranego pliku przed czyszczeniem cache.

Gdy pojawia się regresja wizualna, porównaj ten sam widok przy tej samej szerokości i sprawdź computed styles wadliwego elementu. Brak selektora kieruje do wykrywania źródeł, a selektor przekreślony w DevTools wskazuje konflikt kolejności lub kaskady. Po poprawce wykonaj build produkcyjny i ponownie przejdź krytyczne ścieżki sklepu.

Jeśli wdrożenie powoduje błąd krytyczny, przywróć poprzedni commit lub artefakt razem z poprzednim lockfile. Odtwórz problem na stagingu w osobnym branchu. Rollback jest zakończony, gdy produkcja serwuje poprzedni arkusz, kluczowe widoki działają i logi nie pokazują błędów ładowania CSS.

Zakres migracji zależy od liczby źródeł klas, własnych pluginów, dynamicznych nazw i widoków wymagających kontroli. Podmiana pakietu w prostym projekcie obejmuje mniej zmian niż motyw WordPress ze wspólnymi bibliotekami i rozbudowanym checkoutem. Zakres ustal przed rozpoczęciem pracy, oddzielając zmianę pipeline'u od porządkowania kodu i testów.

Tabela porównuje trzy scenariusze i wskazuje, co zwiększa zakres w każdym z nich. Nie przypisuje scenariuszom stałej liczby godzin, ponieważ zależy ona od istniejącej konfiguracji i wyniku audytu.

Przed estymacją zmapuj szablony, integracje i stany komponentów, które muszą zachować wygląd. Ustal, czy zakres obejmuje tylko build CSS, czy również klasy dynamiczne, zmianę wspieranych przeglądarek i testy stagingowe. Przy rozwoju lub utrzymaniu samej witryny WordPress sprawdź, czy oferta WordPressa odpowiada zakresowi opieki technicznej potrzebnemu po migracji.

• Bootstrap czy Tailwind CSS? Wybór dla strony i sklepu
• Tailwind CSS width: jak ustawiać szerokość elementów
• Tailwind breakpoints: jak dopasować breakpointy do układu strony
• Tailwind CSS toggle: jak wdrożyć dostępny przełącznik