Tailwind Class Çalışmıyor mu? Sık Yapılan Hatalar ve Çözümleri

1. Sınıf adı parçalardan birleştirilmiş

Tailwind kaynak dosyalarınızı bir programlama dili olarak çalıştırmaz, düz metin olarak tarar ve sınıf adına benzeyen parçaları arar. Belgelerin vurguladığı kural şudur: sınıf adları kaynak kodda eksiksiz geçmelidir. Bir şablon ifadesiyle ya da string birleştirmeyle kurulan ad, dosyada hiç bütün olarak yer almadığı için CSS'i üretilmez. Üç satırı birlikte derledik:

<div class="text-{{ hata ? 'red' : 'green' }}-600"></div>
<button class="bg-${renk}-600"></button>
<div class="{{ hata ? 'text-red-600' : 'text-green-600' }}"></div>

v4.3.5 ile derlenen CSS'in utilities katmanı:

@layer utilities {
  .text-green-600 {
    color: var(--color-green-600);
  }
  .text-red-600 {
    color: var(--color-red-600);
  }
}

Yalnızca üçüncü satırdaki iki tam ad üretildi. İlk iki satırda text-red-600 veya bg-blue-600 gibi bir ad hiçbir yerde bütün hâlinde geçmediği için Tailwind bunlardan habersiz kaldı. Çözüm, her olasılığın tam sınıf adını yazmak, gerekiyorsa bir değer tablosundan seçmektir. Sınıflar yalnızca bir veritabanından veya kullanıcı girdisinden geliyorsa, belgelerin önerdiği yol onları @source inline() ile güvenceye almaktır (safelist).

@import "tailwindcss";
@source inline("{hover:,}bg-red-{50,{100..900..100},950}");

Bu satır süslü parantez genişletmesiyle bg-red-50'den bg-red-950'ye kadar bütün tonları ve hover sürümlerini üretir; v4.3.5 derlemesinde 11 temel sınıf ve 11 hover sınıfı çıktı. Ancak safelist çıktıyı büyütür; yalnızca gerçekten gerekli sınıflar için kullanın.

2. Dosya taranmıyor

Belgelere göre Tailwind projenizdeki dosyaları tararken bazılarını otomatik olarak atlar: .gitignore içinde listelenenler, node_modules klasörü, resim ve video gibi ikili dosyalar, CSS dosyaları ve paket yöneticisi kilit dosyaları. Sınıflarınız böyle bir dosyadaysa CSS'leri üretilmez. Bunu küçük bir klasörde denedik: .gitignore içinde gizli/ yazdık, acik.html içine p-3, gizli/sayfa.html içine p-7 koyduk ve yalnızca @import "tailwindcss"; ile derledik:

@layer utilities {
  .p-3 {
    padding: calc(var(--spacing) * 3);
  }
}

p-7 üretilmedi. Giriş dosyasına @source "./gizli"; satırını ekleyip tekrar derlediğimizde ikisi birden geldi:

@layer utilities {
  .p-3 {
    padding: calc(var(--spacing) * 3);
  }
  .p-7 {
    padding: calc(var(--spacing) * 7);
  }
}

Aynı durum, Tailwind ile yazılmış harici bir arayüz kütüphanesi kullandığınızda da ortaya çıkar; kütüphane node_modules içinde olduğu için sınıfları görülmez ve belgeler bunun için @source "../node_modules/..."; yazmayı önerir. Bir diğer klasik hata, source(none) ile otomatik taramayı kapatıp ardından gerekli @source satırlarını eklemeyi unutmaktır. Ayrıca otomatik tespitin başlangıç noktası, belgelere göre varsayılan olarak çalışma dizinidir; derleme komutunu monorepo kökünden çalıştırıyorsanız @import "tailwindcss" source("../src"); ile tabanı açıkça verin.

3. @apply bilinmeyen sınıf hatası

@apply içine Tailwind'in tanımadığı bir ad yazarsanız derleme durur. Bu hata, yazım yanlışlarını yakalaması açısından aslında faydalıdır:

@import "tailwindcss" source(none);
.btn {
  @apply px-4 bg-yok-500;
}

Error: Cannot apply unknown utility class `bg-yok-500`

Daha kafa karıştırıcı olan, var olan bir sınıf için aynı hatayı almaktır. Bu genellikle @apply'ın Tailwind'in yüklenmediği bir stil dosyasında çalıştığını gösterir: Vue veya Svelte bileşenlerinin <style> blokları ya da CSS modülleri gibi. Bu durumu, içinde @import "tailwindcss" olmayan bir dosyayla taklit ettik:

h1 {
  @apply text-2xl font-bold;
}

Error: Cannot apply unknown utility class `text-2xl`. Are you using CSS modules or similar and missing `@reference`? https://tailwindcss.com/docs/functions-and-directives#reference-directive

Hata mesajı çözümü de söylüyor: bu tür dosyaların başına @reference "../../app.css"; (kendi ana stil dosyanız) ya da yalnızca varsayılan temayı kullanıyorsanız @reference "tailwindcss"; ekleyin. Belgelere göre @reference, stil dosyasını çıktıya kopyalamadan yalnızca başvuru için yükler. Ayrıntılar @apply ve bileşen sınıfları yazısında.

4. v3'ten kalan direktifler, adlar ve ayarlar

v3 projesinden kopyalanmış bir giriş dosyası v4'te hata vermeden boş bir çıktı üretebilir. Üç klasik @tailwind satırını, içinde p-4 ve text-red-500 geçen bir HTML dosyasını @source ile göstererek derledik; çıktının tamamı tek satırdan ibaret oldu:

@tailwind base;
@tailwind components;
@tailwind utilities;
@source "./ornek.html";

/*! tailwindcss v4.3.5 | MIT License | https://tailwindcss.com */

Ne Preflight ne de utility sınıfları geldi ve CLI bir uyarı da vermedi. Yükseltme kılavuzuna göre bu üç satırın yerini tek bir @import "tailwindcss"; alır. Benzer sessiz kayıplar kaldırılmış sınıflarda da görülür:

<div class="bg-blue-500 bg-opacity-50 flex-shrink-0 hover:underline shadow-sm"></div>

@layer utilities {
  .flex-shrink-0 {
    flex-shrink: 0;
  }
  .bg-blue-500 {
    background-color: var(--color-blue-500);
  }
  .shadow-sm {
    --tw-shadow: 0 1px 3px 0 var(--tw-shadow-color, rgb(0 0 0 / 0.1)), 0 1px 2px -1px var(--tw-shadow-color, rgb(0 0 0 / 0.1));
    box-shadow: var(--tw-inset-shadow), var(--tw-inset-ring-shadow), var(--tw-ring-offset-shadow), var(--tw-ring-shadow), var(--tw-shadow);
  }
  @media (hover: hover) {
    .hover\:underline:hover {
      text-decoration-line: underline;
    }
  }
}

bg-opacity-50 için hiçbir kural yok; kılavuz bu sınıf ailesinin kaldırıldığını ve yerine bg-blue-500/50 gibi opaklık ekinin kullanılacağını söyler (bkz. renk opaklığı). flex-shrink-0 ise hâlâ derleniyor ama canonicalize onu shrink-0'a çevirir. shadow-sm üretiliyor fakat anlamı değişti: v3'teki shadow görünümü artık bu addadır. Aynı kaymayı rounded, blur ve drop-shadow ölçeklerinde de görürsünüz; kılavuzun yeniden adlandırma tablosu bunları listeler.

Son satır özellikle önemli: kılavuza göre v4 JavaScript yapılandırma dosyasını otomatik olarak bulmaz. Özel renkleriniz veya fontlarınız "kaybolduysa" dosyayı @config "../../tailwind.config.js"; ile açıkça yükleyin ya da değerleri @theme içine taşıyın. Kılavuzda npx @tailwindcss/upgrade adlı bir yükseltme aracı da anılıyor; bu seride npm komutları çalıştırılmadığı için aracı denemedik.

5. Sınıf üretilmiş ama başka bir kural kazanıyor

Derlenmiş CSS'te seçiciyi bulduysanız sorun öncelikle ilgilidir. Üç yaygın neden var. Birincisi, aynı elementte aynı özelliği ayarlayan iki utility vardır ve CSS'te sonra gelen kazanır; HTML'deki sıra hiçbir şey ifade etmez. İkincisi, giriş dosyanıza katmansız yazılmış eski bir kural utility'yi ezer, çünkü Tailwind'in bütün çıktısı katmanlar içindedir. Üçüncüsü, bir responsive varyant (örneğin md:p-8) kendisinden önce gelen px-6 gibi bir sınıfı o breakpoint'te ezer. Bu üç durumun derlenmiş örnekleri çakışan sınıflar ve important ile @layer katmanları yazılarında. Hızlı bir kontrol için tailwindcss canonicalize 'grid flex' gibi bir komut çalıştırabilirsiniz; tamamen ezilen sınıf sonuçtan çıkarılır (bu örnekte sonuç yalnızca grid).

6. Hover dokunmatik ekranda çalışmıyor

Yukarıdaki çıktıda hover:underline kuralının @media (hover: hover) içinde olduğunu gördünüz. Yükseltme kılavuzuna göre v4'te hover varyantı yalnızca birincil giriş aygıtı üzerine gelmeyi destekliyorsa uygulanır; dokunmatik telefonlarda dokunma sonrası "yapışıp kalan" hover renkleri bu sayede oluşmaz. Eski davranışa gerçekten ihtiyacınız varsa kılavuz şu satırı önerir:

@custom-variant hover (&:hover);

  .hover\:underline:hover {
    text-decoration-line: underline;
  }

Bu satırla derlediğimizde medya sorgusu kayboldu. Yine de önemli bir bilgiyi (bir açıklama, bir menü) yalnızca hover ile göstermek yerine tıklama veya odakla da erişilebilir kılmak daha sağlam bir çözümdür. Ayrıntılar hover ve focus durumları yazısında.

7. dark: sınıfı html class="dark" ile çalışmıyor

Belgelere göre dark varyantı varsayılan olarak işletim sisteminin tercihine, yani prefers-color-scheme medya özelliğine bakar. <html class="dark"> eklemek tek başına hiçbir şeyi değiştirmez:

  @media (prefers-color-scheme: dark) {
    .dark\:bg-gray-900 {
      background-color: var(--color-gray-900);
    }
  }

Sınıfla elle geçiş yapmak istiyorsanız varyantı yeniden tanımlamanız gerekir. Aşağıdaki satırla derlediğimizde kural sınıf seçicisine dönüştü:

@custom-variant dark (&:where(.dark, .dark *));

  .dark\:bg-gray-900:where(.dark, .dark *) {
    background-color: var(--color-gray-900);
  }

data-theme niteliğiyle çalışan sürüm ve tema geçiş betiği dark mode yazısında.

8. Başlıklar, listeler ve kenarlıklar "kayboldu"

Bunlar aslında hata değil, Preflight'ın bilinçli sıfırlamalarıdır. v4.3.5 Preflight'ı h1'den h6'ya kadar başlıklarda font-size: inherit ve font-weight: inherit, ol ve ul elementlerinde list-style: none kullanır; resimleri display: block yapar ve bütün elementlerde border: 0 solid ile kenarlığı sıfırlar. Bu yüzden düz bir <h1> paragraf boyutunda görünür ve madde işaretleri çıkmaz. Çözüm, ilgili elementlere sınıf vermek (text-3xl font-bold, list-disc) veya @layer base içinde varsayılan tanımlamaktır. Bir başka kayma da kenarlık renginde: yükseltme kılavuzuna göre border artık varsayılan olarak currentColor kullanır, yani renk belirtmezseniz kenarlık metin renginde çizilir. Ayrıntılar Preflight ve border ve rounded yazılarında.

Adım adım teşhis sırası

Yukarıdaki hataların hepsi aynı kontrol listesiyle bulunabilir. Bir sınıf beklediğiniz gibi davranmıyorsa şu sırayı izleyin; her adım bir öncekinin sonucuna göre bir sonraki şüpheliyi eler:

• Derleme gerçekten çalıştı mı? CLI çıktısında hata mesajı var mı, çıktı dosyası güncel mi? Bir @apply hatası tüm derlemeyi durdurur ve eski CSS'i yerinde bırakır.
• Çıktının başında ne var? Dosya yalnızca lisans satırından ibaretse giriş dosyanız v3 direktifleri kullanıyor olabilir.
• Seçici çıktıda var mı? Yoksa sınıf adının kaynakta bütün hâlinde geçip geçmediğine, dosyanın taranan bir yerde olup olmadığına ve önek kullanıp kullanmadığınıza bakın.
• Seçici hangi koşulun içinde? @media (hover: hover), @media (prefers-color-scheme: dark) veya bir breakpoint bloğu içindeyse, o koşul test ettiğiniz ortamda gerçekleşiyor mu?
• Tarayıcıda kural üstü çizili mi? Öyleyse aynı özelliği ayarlayan başka bir sınıf veya katmansız bir kural kazanıyor; çakışmayı kaldırın.
• Değer beklediğiniz mi? Kural uygulanıyor ama sonuç farklıysa değişkenin tema bloğundaki değerine bakın; v3'ten kalan bir ölçek adı (örneğin shadow-sm) artık farklı bir değere karşılık geliyor olabilir.

Bu sıra kulağa uzun gelse de pratikte çoğu sorun ilk üç adımda çözülür. Önemli olan, sorunu tahminle değil derlenmiş CSS'e bakarak aramaktır; Tailwind'in ürettiği her şey o dosyadadır.

Yükseltme kılavuzunun işaret ettiği bir başka sessiz değişiklik de space-x-* ve space-y-* seçicileridir. v4.3.5 derlemesinde space-y-4, :where(.space-y-4 > :not(:last-child)) seçicisiyle son öge dışındaki her ögeye margin-block-end verdi; space-x-4 ise aynı mantıkla margin-inline-end kullandı. Kılavuz bu değişikliğin büyük sayfalardaki performans sorunları için yapıldığını söyler. Satır içi elementlerle veya kendi margin değerlerini taşıyan ögelerle birlikte kullanıldığında v3'tekinden farklı boşluklar görebilirsiniz; kılavuz bu durumlarda flex veya grid ile gap kullanmayı önerir. Ayrıntılar gap, space-x ve divide yazısında.

Hızlı teşhis tablosu

Sık Sorulan Sorular

Sınıfın üretilip üretilmediğini en hızlı nasıl anlarım?

Derlenmiş CSS'te seçiciyi arayın. Seçicideki özel karakterlerin kaçışlı yazıldığını unutmayın: md:p-8 çıktıda .md\:p-8, px-2.5 ise .px-2\.5 olarak geçer. Derleme komutunun kendisi için Tailwind CLI yazısına bakın.

Hiç hata mesajı yok ama beklediğim CSS çıkmıyor, neden?

Bu yazıdaki örneklerin çoğu tam da böyleydi: parçalı sınıf adı, taranmayan dosya, kaldırılmış bg-opacity-* sınıfı, v3 @tailwind satırları ve önek açıkken yazılan öneksiz sınıflar CLI'da hiçbir uyarı üretmedi. Tailwind tanımadığı parçaları sessizce atlar; belgelere göre tarayıcı, sınıf olabilecek her parçayı dener ve bir utility'ye karşılık gelmeyenleri atar. Hata yalnızca @apply gibi açıkça bir sınıf istediğiniz yerlerde verilir. Bu yüzden "hata yok" demek "sınıf üretildi" demek değildir; kontrolü her zaman çıktı dosyasında yapın.

Değişiklik yaptım ama tarayıcıda bir şey değişmiyor, neden?

Önce CSS'in yeniden derlendiğinden emin olun: CLI'ı --watch olmadan çalıştırıyorsanız her değişiklikten sonra komutu tekrar çalıştırmanız gerekir. Ardından tarayıcının doğru dosyayı yüklediğini ve önbellekten eski sürümü getirmediğini kontrol edin.

Keyfi değer sınıfım neden çalışmıyor?

Keyfi değerlerde boşluk yerine alt çizgi kullanılmalıdır; grid-cols-[1fr 2fr] gibi boşluklu bir yazım tarayıcı için iki ayrı sınıf demektir. Yükseltme kılavuzu ayrıca v4'te grid değerlerindeki virgüllerin artık boşluğa çevrilmediğini belirtir. Ayrıntılar arbitrary values yazısında.

Önek (prefix) açtıktan sonra hiçbir sınıf çalışmıyor, neden?

prefix(tw) açıkken öneksiz sınıflar üretilmez; her sınıfı tw:flex biçiminde yazmanız gerekir. Bunun derlenmiş örneği @layer katmanları yazısında.

Marka adları sahiplerine aittir. Bu yazı bağımsız bir teknik rehberdir; adı geçen kuruluşlarla bayilik veya ortaklık ilişkisi bulunduğu anlamına gelmez.

İlgili içerikler: Tailwind CSS öğrenme rehberi · Sınıf tarama ve @source · Çakışan sınıflar · @apply ve @reference · Preflight · Tailwind CSS v4 yenilikleri