Tailwind CSS Standalone CLI: Node Olmadan Derleme

Standalone CLI nedir, ne zaman tercih edilir?

Resmî Tailwind CLI kurulum sayfası, aracın npm paketi olarak (tailwindcss ve @tailwindcss/cli) kurulabileceğini, ayrıca Node.js gerektirmeyen bağımsız bir çalıştırılabilir dosya olarak da sunulduğunu belirtir. Bağımsız dosyalar Tailwind'in GitHub sürüm sayfasında yayımlanır. Bu biçim özellikle şu durumlarda işe yarar: projede zaten bir JavaScript derleme hattı yoksa (örneğin PHP şablonları, statik HTML ya da Go, Python gibi başka dillerle yazılmış bir arka uç), sunucuda ya da CI ortamında Node kurmak istemiyorsanız veya Tailwind'i yalnızca birkaç sayfalık bir site için denemek istiyorsanız.

Bu yazı için kullanılan dosya, v4.3.5 sürümünün tailwindcss-windows-x64.exe dosyasıdır ve indirildikten sonra SHA256 özeti aynı sürümün sha256sums.txt dosyasındaki değerle karşılaştırılarak doğrulandı. İndirdiğiniz her çalıştırılabilir dosya için bu kontrolü yapmanız iyi bir alışkanlıktır. Dosyayı PATH'e eklemek zorunlu değildir; tam yoluyla da çağırabilirsiniz. Komut satırında çağırdığınızda ilk satırda sürüm bilgisi görünür:

$ tailwindcss --help
≈ tailwindcss v4.3.5

Usage:
  tailwindcss [--input input.css] [--output output.css] [--watch] [--poll=ms]
              [options…]

  tailwindcss build [--input input.css] [--output output.css] [--watch]
                    [--poll=ms] [options…]
  tailwindcss canonicalize [classes...]

Yardım çıktısına göre ana komutun iki yazımı vardır: doğrudan bayraklarla ya da build alt komutuyla. Denemede tailwindcss build -i giris.css -o b.css komutu, alt komutsuz çalıştırmayla bayt bayt aynı dosyayı üretti. Diğer alt komut canonicalize'dır ve yazının ikinci yarısında anlatılıyor.

Bayrakların tamamı

v4.3.5 yardım çıktısında listelenen seçenekler şunlardır. Açıklamalar yardım metninden ve bu yazıdaki denemelerden alındı.

İlk derleme: giriş dosyası ve çıktı

Standalone CLI'nin girdisi bir CSS dosyasıdır. En sade hali tek satırdır: @import "tailwindcss";. Bu satırla derleyici otomatik kaynak taramasını açar ve çalışma dizininden başlayarak dosyaları tarar. Örneklerde çıktıyı küçük tutmak ve başka klasörlerin taranmasını önlemek için taramayı kapatıp tek bir HTML dosyasını açıkça kaydettik. Bu tekniklerin ayrıntısı @source direktifi yazısındadır.

@import "tailwindcss" source(none);
@source "./ornek.html";

<p class="p-4 text-center md:p-8">Merhaba</p>

NO_COLOR=1 tailwindcss -i giris.css -o cikti.css
≈ tailwindcss v4.3.5

Done in 29ms

Süre makineden makineye değişir; burada önemli olan çıkış kodunun sıfır olması ve dosyanın yazılmasıdır. NO_COLOR=1 ortam değişkeni terminal renk kodlarını kapatır ve özellikle çıktıyı bir dosyaya ya da CI günlüğüne yönlendirirken okunabilirliği artırır. v4.3.5 ile derlenen CSS'in utilities katmanı:

@layer utilities {
  .p-4 {
    padding: calc(var(--spacing) * 4);
  }
  .text-center {
    text-align: center;
  }
  @media (width >= 48rem) {
    .md\:p-8 {
      padding: calc(var(--spacing) * 8);
    }
  }
}

-o bayrağını hiç vermezseniz varsayılan değer - olduğu için CSS standart çıktıya yazılır. Bu, sonucu başka bir araca boru ile aktarmak ya da hızlıca terminalde görmek için kullanışlıdır. Denemede tailwindcss -i giris.css komutu aynı CSS'i ekrana bastı. --silent ise "Done in" gibi bilgi satırlarını gizler; hata olduğunda mesaj yine görünür.

--minify, --optimize ve --map karşılaştırması

Aynı giriş dosyasını dört farklı şekilde derledik ve dosya boyutlarını ölçtük. Değerler yalnızca bu küçük örneğe aittir (Preflight dahil, üç utility sınıfı); büyük projelerde oranlar farklı olur.

tailwindcss -i giris.css -o normal.css
tailwindcss -i giris.css -o min.css --minify
tailwindcss -i giris.css -o opt.css --optimize
tailwindcss -i giris.css -o map.css --map

Tablodaki en ilginç ayrıntı, --optimize ve --minify çıktılarında medya sorgusunun yazımının değişmesidir. Bayraksız derlemede @media (width >= 48rem) olan sorgu, optimize edilmiş dosyada şöyle görünür:

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

  .text-center {
    text-align: center;
  }

  @media (min-width: 48rem) {
    .md\:p-8 {
      padding: calc(var(--spacing) * 8);
    }
  }
}

Küçültülmüş dosyanın son kısmı ise tek satırdır:

@layer components;@layer utilities{.p-4{padding:calc(var(--spacing) * 4)}.text-center{text-align:center}@media (min-width:48rem){.md\:p-8{padding:calc(var(--spacing) * 8)}}}

İki sorgu aynı koşulu ifade eder; aralık sözdizimi (width >= 48rem) ile klasik min-width yazımı arasındaki fark yalnızca biçimseldir. Optimize adımı klasik min-width yazımını tercih ediyor. Yani "küçültme yalnızca boşlukları siler" düşüncesi tam doğru değildir; optimize adımı bazı ifadeleri eşdeğer biçimlere de çevirir. Üretim ortamında yayınladığınız dosya için genellikle --minify yeterlidir; --optimize aynı dönüşümleri okunabilir biçimde görmek istediğinizde işe yarar.

--map bayrağı ayrı bir .map dosyası yazmadı; haritayı CSS dosyasının sonuna /*# sourceMappingURL=data:application/json;base64,... yorumu olarak gömdü. Dosya boyutunun yaklaşık on kat büyümesi bundandır. Kaynak haritası, tarayıcı geliştirici araçlarında bir kuralın hangi kaynak satırından geldiğini görmeyi kolaylaştırır; ancak bu haliyle üretime göndermek gereksiz bayt taşımak demektir.

--watch ve --poll: geliştirme sırasında izleme

Resmî CLI kurulum sayfasındaki örnek komut --watch bayrağıyla verilir; bu modda CLI açık kalır ve kaynak dosyalar değiştikçe CSS'i yeniden üretir. Yardım çıktısına göre --watch=always biçimi, standart girdi kapansa bile izlemeyi sürdürür; bu, CLI'yi başka bir sürecin alt süreci olarak çalıştırdığınız düzenlerde önemlidir. --poll ise izleme sırasında dosya sistemi olayları yerine yoklama (polling) yöntemini kullanır ve yardım metnindeki --poll[=ms] yazımından anlaşıldığı gibi isteğe bağlı bir milisaniye değeri alır; varsayılanı kapalıdır.

İzleme modu kendiliğinden bitmediği için bu yazıda çalıştırılmadı; açıklama yalnızca yardım metnine ve resmî sayfaya dayanır. Geliştirirken bir terminal sekmesinde izleme modunu açık tutup, yayın için ayrı bir --minify derlemesi yapmak yaygın bir iş akışıdır.

tailwindcss -i ./src/input.css -o ./src/output.css --watch

Derleme hatalarını okumak

Tailwind HTML'de tanımadığı bir sınıfı sessizce atlar, ama CSS içinde @apply ile bilinmeyen bir sınıf kullanılırsa derleme durur. Aşağıdaki girişte bg-yok-500 diye bir renk yoktur:

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

CLI çerçeveli bir hata kutusu basar ve sıfırdan farklı bir çıkış koduyla (bu denemede 1) sonlanır. Mesaj satırı şudur:

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

Çıkış kodunun sıfır olmaması, CLI'yi bir CI adımında çalıştırdığınızda derlemenin başarısız sayılmasını sağlar. Bu hatanın nedenleri ve çözümleri @apply yazısında ve sık hatalar yazısında ayrıntılı ele alınır.

canonicalize: sınıf adlarını sadeleştirmek

canonicalize alt komutu, verdiğiniz sınıfları tasarım sistemine göre önerilen biçime çevirir. Eski adlar, gereksiz keyfi değerler ve birleştirilebilecek sınıf çiftleri bu komutla temizlenebilir. Her argüman bir sınıf grubu olarak işlenir ve her grup için bir satır çıktı verilir.

tailwindcss canonicalize bg-gradient-to-r flex-grow flex-shrink-0 "mt-[16px]" "p-[1rem]" "w-[50%]" "bg-[var(--renk)]" p-4
bg-linear-to-r
grow
shrink-0
mt-[16px]
p-4
w-[50%]
bg-(--renk)
p-4

Sonuçlar şöyle okunabilir: bg-gradient-to-r, flex-grow ve flex-shrink-0 hâlâ derlenen eski adlardır ve bg-linear-to-r, grow, shrink-0 biçimine çevrildi. p-[1rem] ölçekteki p-4 ile aynı değeri verdiği için ona dönüştü. bg-[var(--renk)] ise kısa değişken sözdizimi bg-(--renk) oldu. mt-[16px] ve w-[50%] olduğu gibi kaldı; piksel değeri rem tabanlı ölçeğe ancak kök yazı boyutu bilinseydi eşlenebilirdi. Eski adlarla v3 geçişinin bütün ayrıntısı Tailwind v4 yenilikleri yazısındadır.

Bir argümanın içine boşlukla ayrılmış birden fazla sınıf yazarsanız komut onları birlikte değerlendirir ve birleştirilebilenleri birleştirir:

tailwindcss canonicalize "px-4 py-4" "mt-2 mr-2 mb-2 ml-2"
p-4
m-2

Makine tarafından işlenecek çıktı için --format json ya da --format jsonl kullanılabilir. JSON çıktısı her giriş için değişip değişmediğini de bildirir:

tailwindcss canonicalize --format json flex-grow "mt-[16px]"
[
  {
    "input": "flex-grow",
    "output": "grow",
    "changed": true
  },
  {
    "input": "mt-[16px]",
    "output": "mt-[16px]",
    "changed": false
  }
]

Eksiyle başlayan sınıflar ve --stream

Denemede önemli bir tuzakla karşılaştık. Komut satırında eksiyle başlayan bir sınıf (-mt-[10px]) argüman olarak verildiğinde CLI onu bir bayrak gibi yorumladı, kullanım bilgisini bastı ve "No candidate groups provided" mesajıyla sonlandı. Bu sınıf başka sınıflarla aynı komutta verildiğinde ise çıktı satırlarının sayısı giriş sayısından azdı, yani bir sınıfın sonucu kayboldu. Çözüm, sınıfları --stream ile standart girdiden satır satır vermektir:

printf -- '-mt-[10px]\nflex-grow flex-shrink-0 p-4\npx-4 py-4\n' | tailwindcss canonicalize --stream
mt-[-10px]
shrink-0 grow p-4
p-4

Bu modda her satır bir grup sayılır ve sonuç aynı sırayla yazılır. Gruptaki sınıfların sırası da değişebilir; ikinci satırda shrink-0 grow p-4 sırası çıktı. --stream, editör eklentileri ya da betikler gibi uzun süre çalışan araçlarla entegrasyon için de uygundur.

Kendi temanızla canonicalize

Varsayılan olarak komut, @import "tailwindcss"; ile yüklenen varsayılan tasarım sistemini kullanır. Projenizde @theme ile tanımlanmış değerler varsa --css ile giriş dosyanızı göstermeniz gerekir. Aşağıdaki denemede tema dosyasında --color-marka: #5b21b6 tanımlıydı ve hem değişken referansı hem de aynı onaltılık değer tema sınıfına çevrildi:

@import "tailwindcss";
@theme { --color-marka: #5b21b6; }

tailwindcss canonicalize --css t.css "bg-[var(--color-marka)]" "bg-[#5b21b6]"
bg-marka
bg-marka

Bu özellik, eski bir projeyi temaya taşırken sabit renk kodlarını bulup tema sınıflarına çevirmenin pratik bir yoludur. Tema tanımlamanın ayrıntıları @theme yazısında anlatılır.

Tipik iş akışı: geliştirme ve yayın

Standalone CLI ile çalışan küçük bir projede iki ayrı derleme komutu tutmak yeterlidir. Geliştirirken izleme modu açık bir terminalde çalışır ve okunabilir çıktı üretir; yayın öncesinde ise aynı giriş dosyası küçültülerek ayrı bir dosyaya derlenir. Yayın komutunu bir betiğe ya da CI adımına koyarsanız, --silent bilgi satırlarını gizler ve hata durumunda sıfırdan farklı çıkış kodu adımı başarısız sayar.

# geliştirme (izleme modu, bu yazıda çalıştırılmadı)
tailwindcss -i giris.css -o cikti.css --watch

# yayın
tailwindcss -i giris.css -o cikti.min.css --minify --silent

Yayın komutu bu yazıdaki denemelerde kullanılan bayrakların bir birleşimidir; her biri ayrı ayrı çalıştırıldı. Giriş dosyasında source(none) kullanmıyorsanız komutu her zaman proje kökünden çalıştırmaya dikkat edin, çünkü otomatik tarama çalışma dizininden başlar. Farklı bir dizinden çalıştırmanız gerekiyorsa --cwd bayrağı ya da CSS içindeki source("...") ayarı başlangıç noktasını sabitler. Denemede bir üst klasörden çalıştırılan tailwindcss --cwd s1 -i src/giris.css -o cwd.css komutu, giriş ve çıktı yollarını da taramayı da s1 klasörüne göre çözdü; çıktı s1/cwd.css olarak yazıldı ve o klasördeki sınıflar üretildi. Derlenen dosyayı sayfanıza her zamanki gibi bir <link> etiketiyle bağlarsınız; tarayıcı tarafında Tailwind'e ait başka bir dosyaya gerek kalmaz.

npm üzerinden CLI ile farkı

Resmî kurulum sayfası CLI'yi npm ile kurmayı da gösterir: npm install tailwindcss @tailwindcss/cli ve ardından npx @tailwindcss/cli -i ./src/input.css -o ./src/output.css --watch. Bu yazıda npm komutları çalıştırılmadı. Bayraklar ve giriş dosyası biçimi aynıdır; fark, programın Node.js üzerinden çalışması ve sürümün package.json ile projeye kilitlenmesidir. Ekibinizde zaten Node kullanılıyorsa npm yolu sürüm yönetimini kolaylaştırır; kullanılmıyorsa standalone dosya ek bağımlılık getirmez. Node kurulumu için Node.js kurulumu ve sürüm yöneticileri yazısına bakabilirsiniz.

Sık yapılan hatalar

• Yayın dosyasında kaynak haritası bırakmak: --map haritayı CSS'in içine gömdüğü için dosya büyür; yayın derlemesinde bu bayrağı kullanmayın.
• Otomatik taramanın çok geniş başlaması: @import "tailwindcss"; çalışma dizininden tarar; CLI'yi yanlış klasörde çalıştırmak alakasız dosyaların taranmasına yol açabilir. --cwd ya da source() ile başlangıç noktasını belirleyin.
• Eksiyle başlayan sınıfları argüman vermek: canonicalize bunları bayrak sanar; --stream kullanın.
• Hata çıktısını görmezden gelmek: @apply hatasında çıkış kodu sıfırdan farklıdır; betiklerinizde çıkış kodunu kontrol edin.
• Doğrulanmamış dosya çalıştırmak: Çalıştırılabilir dosyayı yalnızca resmî sürüm sayfasından indirin ve özetini kontrol edin.

Sık Sorulan Sorular

Standalone CLI ile npm sürümü aynı CSS'i üretir mi?

Her ikisi de aynı Tailwind derleyicisini kullanır ve aynı bayrakları kabul eder. Bu yazıdaki çıktılar yalnızca standalone v4.3.5 ile üretildi; farklı sürümler farklı CSS üretebileceğinden projede tek bir sürüme bağlı kalın.

--minify ile --optimize arasındaki fark nedir?

İkisi de optimize eder; --minify ayrıca boşlukları atar. Denemede ikisi de medya sorgusunu min-width biçimine çevirdi, ama yalnızca --minify çıktısı tek satıra indi.

Ayrı bir .map dosyası üretebilir miyim?

v4.3.5 ile yapılan denemede --map haritayı satır içi olarak yazdı. Yardım metninde ayrı dosya için bir seçenek listelenmiyor.

canonicalize kaynak dosyalarımı değiştirir mi?

Hayır. Komut yalnızca verdiğiniz sınıfları dönüştürüp sonucu yazdırır; dosyalarınıza dokunmaz. Sonucu kendiniz uygularsınız.

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 · Vite ve PostCSS kurulumu · Sınıf tarama ve @source · Utility class mantığı · Tailwind sık hatalar