Tailwind CSS Kurulumu: Vite, PostCSS ve npm CLI Yolları

Hangi yolu seçmeli?

Seçim çoğu zaman projenizin zaten kullandığı araca göre yapılır. Resmî Vite sayfası, Vite eklentisini Laravel, SvelteKit, React Router, Nuxt ve SolidJS gibi framework'lerle entegrasyonun en sorunsuz yolu olarak tanıtır. Next.js ya da Angular gibi kendi derleme hattını yöneten bir framework kullanıyorsanız resmî framework kılavuzları sayfası, Next.js, Laravel, Nuxt, SolidJS, SvelteKit, Gatsby, Angular, Ruby on Rails, React Router, TanStack Start, Phoenix, Parcel, Symfony, Meteor, AdonisJS, Ember.js, Astro, Qwik ve Rspack için ayrı adımlar sunar. Listede olmayan bir araç için sayfa CLI, Vite eklentisi ya da PostCSS eklentisinden birini önerir.

Bu yolların hepsi aynı derleyiciyi kullanır; sınıf adları, @theme, @source, @utility gibi direktifler her birinde aynı şekilde çalışır. Yani bu serideki konu yazılarında öğrendiğiniz her şey, hangi kurulum yolunu seçerseniz seçin geçerlidir. Kurulum yolunu değiştirmek, CSS dosyanıza değil yalnızca derleme yapılandırmanıza dokunur.

Vite ile kurulum

Resmî sayfa altı adım tanımlar. Henüz bir projeniz yoksa ilk adım Create Vite ile yeni proje oluşturmaktır:

npm create vite@latest my-project
cd my-project

İkinci adımda Tailwind ve Vite eklentisi kurulur. Tailwind skill notları da Vite yolunu önerilen yol olarak gösterir ve aynı komutu verir:

npm install tailwindcss @tailwindcss/vite

Üçüncü adım, eklentiyi Vite yapılandırmasına eklemektir. Belgedeki vite.config.ts şöyledir:

import { defineConfig } from 'vite'
import tailwindcss from '@tailwindcss/vite'

export default defineConfig({
  plugins: [
    tailwindcss(),
  ],
})

Projenizde zaten başka eklentiler varsa (örneğin bir React ya da Vue eklentisi), tailwindcss() çağrısını aynı plugins dizisine eklemeniz yeterlidir; mevcut yapılandırmayı silmeniz gerekmez. Dördüncü adımda ana CSS dosyanıza (belgedeki örnekte src/style.css) Tailwind'i içe aktarırsınız:

@import "tailwindcss";

Beşinci adım geliştirme sunucusunu başlatmaktır; belge npm run dev komutunu ya da package.json dosyanızda tanımlı başka bir komutu kullanabileceğinizi belirtir. Son adımda CSS dosyasının sayfaya bağlandığından emin olup sınıfları kullanırsınız:

npm run dev

<!doctype html>
<html>
  <head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <link href="/src/style.css" rel="stylesheet">
  </head>
  <body>
    <h1 class="text-3xl font-bold underline">
      Hello world!
    </h1>
  </body>
</html>

Vite yolunda <link> etiketi derlenmiş bir dosyayı değil, doğrudan kaynak CSS dosyasını gösterir; dönüşümü Vite yapar. Bir framework kullanıyorsanız CSS'i sayfaya bağlama işini framework sizin yerinize üstlenebilir. Belgede de bu not yer alır. Viewport meta etiketinin neden gerekli olduğunu mobil uyumluluk yazısında okuyabilirsiniz.

PostCSS ile kurulum

PostCSS yolunda üç paket kurulur; skill notlarındaki komut da aynıdır:

npm install tailwindcss @tailwindcss/postcss postcss

Ardından eklenti PostCSS yapılandırmasına eklenir. Belge postcss.config.mjs dosyasını ya da projenizde PostCSS'in yapılandırıldığı başka bir yeri gösterir:

export default {
  plugins: {
    "@tailwindcss/postcss": {},
  }
}

Sonraki adımlar Vite yolundakiyle aynıdır: CSS dosyasına @import "tailwindcss"; yazılır, npm run dev ya da projenizin kendi komutuyla derleme başlatılır ve derlenmiş CSS sayfanın <head> bölümüne bağlanır. Belgedeki örnek HTML'de bağlantı /dist/styles.css dosyasını gösterir; yani PostCSS yolunda çıktı dosyasının adı ve yeri sizin derleme aracınıza bağlıdır. Resmî sayfa, PostCSS kurulumunun derleme araçları arasında farklılık gösterdiğini ve araca özgü talimatlar için framework kılavuzlarına bakılması gerektiğini de not eder.

Resmî uyumluluk sayfası ayrıca v4'ün @import ifadelerini derleme sırasında kendisinin birleştirdiğini, bunun için postcss-import gibi ayrı bir eklentiye gerek olmadığını belirtir. Eski bir PostCSS yapılandırmasını taşıyorsanız bu, kaldırabileceğiniz eklentilerden biridir; v3 tarafındaki diğer değişiklikler Tailwind v4 yenilikleri yazısında anlatılır.

npm ile CLI kurulumu

Derleme aracı kullanmayan ama Node bulunan projelerde resmî CLI sayfası şu üç adımı verir: paketleri kurmak, src/input.css gibi bir dosyaya @import "tailwindcss"; yazmak ve CLI'yi izleme modunda çalıştırmak.

npm install tailwindcss @tailwindcss/cli
npx @tailwindcss/cli -i ./src/input.css -o ./src/output.css --watch

Bu yolda HTML, derlenmiş çıktı dosyasını (./output.css) gösterir. Bayrakların tamamı, --minify ve --map karşılaştırması ile hata çıktıları standalone CLI yazısında gerçek çalıştırmalarla anlatıldı; npm sürümü aynı bayrakları kullanır.

@import "tailwindcss" aslında neyi içe aktarır?

Üç yolun ortak noktası olan bu tek satır, Tailwind'in üç parçasını katmanlara yerleştirir. Resmî Preflight sayfası bu satırın açılımını şöyle gösterir:

@layer theme, base, components, utilities;
@import "tailwindcss/theme.css" layer(theme);
@import "tailwindcss/preflight.css" layer(base);
@import "tailwindcss/utilities.css" layer(utilities);

theme.css renk, boşluk, yazı tipi gibi tema değişkenlerini, preflight.css tarayıcı farklarını düzelten temel stilleri, utilities.css ise kaynaklarınızda bulunan sınıfların kurallarını getirir. Bu parçaları ayrı ayrı içe aktararak örneğin Preflight'ı kapatabilirsiniz; bu Preflight yazısında gösterilir. Katmanların sırası ve kendi CSS'inizin nereye yazılacağı ise katmanlar yazısının konusudur.

Belgedeki örnek sayfanın kullandığı üç sınıfı, aynı @import satırıyla standalone CLI'de derledik. Bu, Vite ya da PostCSS yolunda tarayıcıya ulaşacak kuralların da aynı derleyiciden geldiğini görmenin en kısa yoludur:

@import "tailwindcss" source(none);
@source inline("text-3xl font-bold underline");

v4.3.5 ile derlenen CSS (theme katmanında --text-3xl: 1.875rem, --text-3xl--line-height: calc(2.25 / 1.875) ve --font-weight-bold: 700 tanımlanır):

/* (kısaltıldı) */
@layer utilities {
  .text-3xl {
    font-size: var(--text-3xl);
    line-height: var(--tw-leading, var(--text-3xl--line-height));
  }
  .font-bold {
    --tw-font-weight: var(--font-weight-bold);
    font-weight: var(--font-weight-bold);
  }
  .underline {
    text-decoration-line: underline;
  }
}

Vite ve PostCSS yollarında source(none) yazmanız gerekmez; o satır burada yalnızca derlemeyi tek bir sınıf listesiyle sınırlamak için kullanıldı. Normal kurulumda derleyici proje dosyalarınızı kendisi tarar ve .gitignore içindeki yolları, node_modules klasörünü, ikili dosyaları ve CSS dosyalarını atlar. Hangi dosyaların tarandığını değiştirmek için @source direktifi yazısına bakın.

Play CDN: yalnızca deneme için

Resmî Play CDN sayfası, derleme adımı olmadan doğrudan tarayıcıda Tailwind denemeyi sağlayan bir betik tanımlar. Sayfa açık bir uyarı içerir: Play CDN geliştirme amaçlıdır ve üretim için tasarlanmamıştır. Üretimde Vite, PostCSS ya da CLI gibi bir derleme aracı kullanılması önerilir.

<script src="https://cdn.jsdelivr.net/npm/@tailwindcss/browser@4"></script>

Bu betikle <style type="text/tailwindcss"> etiketi içinde @theme gibi Tailwind direktiflerini de kullanabilirsiniz. Kısa bir prototip ya da bir sınıfın davranışını hızlıca görmek için yeterlidir; ancak derleme tarayıcıda yapıldığı için yayındaki bir sitede kullanılmamalıdır.

Uyumluluk notları: Sass, CSS modülleri ve style blokları

Resmî uyumluluk sayfası kurulum sırasında sık sorulan üç konuyu ele alır. Birincisi önişlemcilerdir: v4'ün Sass, Less veya Stylus ile birlikte kullanılmak üzere tasarlanmadığı, Tailwind'in kendisinin bir önişlemci gibi düşünülmesi gerektiği belirtilir. İçe aktarma, değişken (yerel CSS değişkenleri), iç içe yazım ve döngü gibi ihtiyaçların Tailwind tarafından karşılandığı anlatılır. İkincisi CSS modülleridir: birlikte çalışabilirler, ama belge bunu mümkünse önermez, çünkü derleme araçları her modülü ayrı işlediği için Tailwind her modül için ayrı çalışır.

Üçüncüsü Vue, Svelte ve Astro bileşenlerindeki <style> bloklarıdır. Belgeye göre bu bloklar CSS modülleri gibi davranır ve aynı dezavantajları taşır; öneri, sınıfları doğrudan işaretlemede kullanmaktır. <style> bloğunda @apply kullanmanız gerekiyorsa blok başına @reference ile ana CSS dosyanızı göstermelisiniz. Bu konu @apply ve bileşen sınıfları yazısında ayrıntılandırılır. Belge ayrıca v4'ün modern tarayıcılar için tasarlandığını ve test edildiğini belirtir; hedef tarayıcılarınız için uyumluluk sayfasındaki sürüm bilgilerine bakmanız gerekir.

Kurulumdan sonra ilk kontrol

Kurulumun çalışıp çalışmadığını anlamanın en basit yolu, belgedeki text-3xl font-bold underline başlığını sayfaya koyup tarayıcıda büyük, kalın ve altı çizili bir başlık görmektir. Görmüyorsanız şu sırayla bakın: CSS dosyasında @import "tailwindcss"; satırı var mı, CSS dosyası sayfaya bağlı mı, Vite yolunda eklenti plugins dizisinde mi, PostCSS yolunda eklenti yapılandırma dosyasında mı. Sınıflar yazıldığı halde CSS üretilmiyorsa sorun büyük olasılıkla taramadadır; HTML'in bulunduğu klasör .gitignore içinde olabilir ya da sınıf adı kodda parça parça birleştiriliyor olabilir. Bu tür sorunlar sık hatalar yazısında toplanmıştır.

Kurulumdan sonra şaşırtan bir başka durum, sınıf vermediğiniz başlıkların ve listelerin düz metin gibi görünmesidir. Bunun nedeni Preflight'tır: Tailwind başlık etiketlerinin tarayıcı varsayılan boyutlarını sıfırlar, bu yüzden <h1> kendiliğinden büyük görünmez; boyutu text-3xl gibi bir sınıf verir. Kurulum doğru olduğu halde başlıklar düz metin gibi görünüyorsa bu beklenen davranıştır.

Monorepo ve tarama başlangıç noktası

Kurulum yolu ne olursa olsun, derleyici varsayılan olarak çalışma dizinini taramanın başlangıç noktası kabul eder. Resmî sınıf tespiti sayfası, derlemelerin monorepo kökünden çalıştırıldığı projelerde bunun istenmeyen sonuçlar doğurabileceğini ve başlangıç yolunun @import "tailwindcss" source("../src"); biçiminde açıkça verilebileceğini anlatır. Bu yol stil dosyasına göre çözülür. Böylece Vite ya da PostCSS hangi klasörden çalıştırılırsa çalıştırılsın tarama aynı klasörden başlar. Birden fazla uygulamanın tek depoda durduğu düzenlerde her uygulamanın kendi CSS dosyasında bu ayarı yapmak, bir uygulamanın sınıflarının ötekinin CSS'ine sızmasını önler.

Editörü hazırlamak

Kurulumu bitirdikten sonra editörünüz @theme, @source ya da @utility gibi Tailwind'e özgü at-rule'ları tanımayıp uyarı verebilir. Resmî editör kurulumu sayfası, VS Code için resmî Tailwind CSS IntelliSense eklentisini önerir; eklenti bu sözdizimi için ayrı bir dil modu, sınıf tamamlama, hover önizlemesi ve linting sağlar. Bazı editörlerde yerleşik CSS doğrulamasını kapatmanız gerekebileceği de belirtilir. Sınıfları önerilen sırada dizmek için resmî Prettier eklentisi vardır. Bu araçlar burada kurulmadı; bilgiler resmî sayfadan aktarıldı.

Sık yapılan hatalar

• Play CDN'i yayına almak: Resmî sayfa bunu üretim için uygun görmez; bir derleme yolu seçin.
• Vite yolunda PostCSS eklentisini de eklemek: Vite eklentisi tek başına yeterlidir; iki entegrasyonu birlikte kurmak belgelenmiş bir adım değildir.
• Sass dosyasının içine Tailwind koymak: Uyumluluk sayfası v4'ün önişlemcilerle kullanılmak üzere tasarlanmadığını belirtir.
• Eski v3 yapılandırmasını aynen taşımak: v4'te yapılandırma CSS içinde @theme ile yapılır; geçiş için ilgili yazıya bakın.
• Derlenmiş CSS yerine kaynak dosyayı bağlamak (CLI ve PostCSS yolunda): Bu yollarda sayfaya üretilen çıktı dosyası bağlanmalıdır.

Sık Sorulan Sorular

Vite eklentisi mi, PostCSS eklentisi mi daha iyi?

Belge bir sıralama yapmaz; Vite eklentisini Vite tabanlı framework'lerle en sorunsuz entegrasyon olarak tanıtır. Projenizde Vite varsa onu, yalnızca PostCSS hattı varsa PostCSS eklentisini kullanmak en az değişikliği gerektirir.

tailwind.config.js dosyası gerekli mi?

Bu yazıdaki hiçbir kurulum adımı bu dosyayı oluşturmaz; özelleştirme CSS içinde yapılır. Eski bir JavaScript yapılandırmasını yüklemek için @config uyumluluk direktifi vardır; ayrıntılar fonksiyonlar ve uyumluluk direktifleri yazısındadır.

Node kurmadan bu kurulumları yapabilir miyim?

Vite, PostCSS ve npm CLI yolları Node gerektirir. Node olmadan çalışmak için standalone CLI dosyasını kullanabilirsiniz.

Kurulumdan sonra hangi konularla devam etmeliyim?

Önce sınıf adlarının nasıl okunduğunu anlatan utility class mantığı yazısını, ardından kurulumun görünmez parçası olan sınıf taramasını ve Preflight'ı okumanızı öneririz. Sonrasında boşluk, düzen, renk ve tipografi yazılarına geçebilirsiniz; bütün sıra Tailwind CSS öğrenme rehberi sayfasında öğrenme yoluna göre listelenmiştir.

Derlenen siteyi nerede yayınlarım?

Derleme sonucu sıradan HTML, CSS ve JavaScript dosyalarıdır; statik dosya sunan her ortamda yayınlanabilir. Seçenekler için statik site hostingi yazısına bakabilirsiniz.

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 · Standalone CLI · Sınıf tarama ve @source · Preflight · Node.js kurulumu