Lewati ke konten

Tailwind CSS

Blockstudio menyertakan dukungan bawaan untuk Tailwind CSS v4. Saat diaktifkan, setiap halaman frontend dikompilasi di sisi server melalui TailwindPHP dengan caching berbasis file otomatis. Di editor blok, skrip Tailwind CDN yang dibundel menyediakan pratinjau langsung saat Anda mengedit.

Tanpa langkah build, tanpa CLI, tanpa Node.js yang diperlukan.

Cara Kerjanya

Blockstudio menggunakan dua strategi kompilasi terpisah bergantung pada konteksnya:

Frontend (Sisi Server)

Pada setiap permintaan frontend, Blockstudio menangkap HTML halaman lengkap melalui buffer output, mengekstrak semua kandidat kelas CSS, hanya mengompilasi CSS yang benar-benar digunakan, lalu menyisipkan hasilnya sebagai tag <style> sebaris sebelum </head>.

Alur kompilasi:

  1. WordPress merender seluruh HTML halaman ke dalam buffer output
  2. TailwindPHP::extractCandidates() memindai HTML dan mengekstrak semua kandidat nama kelas CSS potensial (regex cepat, tanpa kompilasi)
  3. Kandidat yang diurutkan di-hash bersama konfigurasi CSS untuk membuat kunci cache
  4. Saat cache hit: CSS hasil kompilasi dibaca dari disk dan disisipkan
  5. Saat cache miss: TailwindPHP::generate() mengompilasi CSS, menulisnya ke direktori cache, lalu menyisipkannya

CSS hasil kompilasi disisipkan sebagai berikut:

HTML
<style id="blockstudio-tailwind">
  /* compiled CSS */
</style>

Ini mencakup preflight Tailwind (reset CSS) dan semua kelas utilitas yang cocok.

Editor (Sisi Klien)

Di dalam editor blok, skrip Tailwind CDN yang dibundel (build browser dari Tailwind CSS v4) berjalan di sisi klien. Skrip ini menyediakan pratinjau langsung seketika saat Anda mengetik nama kelas, tanpa bolak-balik ke server. CDN hanya dimuat di editor dan tidak pernah disajikan di frontend.

Saat assets.reset.enabled aktif, Blockstudio juga memulihkan utilitas tampilan dan posisi umum milik Tailwind di dalam kanvas editor. Ini mencegah kelas tingkat wrapper seperti flex, grid, absolute, fixed, dan sticky ditimpa oleh aturan wrapper blok editor WordPress, sehingga tata letak berbasis utilitas lebih sesuai dengan frontend.

Mengaktifkan Tailwind

Tambahkan konfigurasi tailwind ke blockstudio.json Anda:

JSON
{
  "$schema": "https://blockstudio.dev/schema/blockstudio",
  "tailwind": {
    "enabled": true
  }
}

Atau aktifkan melalui filter:

PHP
add_filter('blockstudio/settings/tailwind/enabled', '__return_true');

Saat enabled bernilai true, setiap halaman frontend akan memiliki Tailwind CSS yang dikompilasi dan disisipkan secara otomatis. Anda dapat menggunakan kelas utilitas Tailwind di mana saja: dalam templat blok, templat tema, filter the_content, atau HTML apa pun yang muncul di output halaman.

Output frontend

CSS hasil kompilasi disisipkan sebaris secara default, sehingga mempertahankan output yang digunakan versi sebelumnya. Situs dengan banyak aturan bersama dapat memilih stylesheet dengan hash konten:

JSON
{
  "tailwind": {
    "enabled": true,
    "output": "link"
  }
}

"output": "link" mengeluarkan file cache tailwind/{content-hash}.css yang sudah ada sebagai <link rel="stylesheet">. URL berubah saat identitas runtime, kandidat, mesin, atau input CSS berubah, sehingga browser dan cache edge dapat menyimpan URL lama dengan aman. Atur server web atau CDN untuk mengirim header Cache-Control: public, immutable berumur panjang bagi cakupan cache ini.

Root cache default berada di lokasi publik di bawah wp-content. Jika cache.path mengarah ke volume absolut privat, Blockstudio akan kembali menggunakan CSS sebaris kecuali filter blockstudio/files/url yang sudah ada menyediakan URL publik untuk cakupan tailwind:

PHP
add_filter(
    'blockstudio/files/url',
    function (string $url, string $path, string $scope): string {
        if ('tailwind' !== $scope) {
            return $url;
        }

        return 'https://static.example.com/blockstudio/' . basename($path);
    },
    10,
    3
);

Helper komposisi templat

Blockstudio menyediakan mesin TailwindPHP bundel yang sama untuk templat PHP. Tidak diperlukan salinan di sisi tema ataupun implementasi fallback:

PHP
$classes = bs_tw_merge('px-2 text-sm', 'px-4');
// text-sm px-4

$button = bs_tw_variants([
    'base' => 'inline-flex items-center',
    'variants' => [
        'size' => [
            'sm' => 'h-8 px-3',
            'lg' => 'h-12 px-6',
        ],
    ],
    'defaultVariants' => [
        'size' => 'sm',
    ],
]);

echo $button(['size' => 'lg', 'class' => 'rounded']);

bs_tw_merge() menerima nilai kelas bertingkat dan menyelesaikan konflik Tailwind utility. bs_tw_variants() mengembalikan fungsi yang dapat dipanggil bergaya CVA dan mendukung base, variants, default variants, compound variants, class, dan className.

Konfigurasi

Tailwind v4 menggunakan pendekatan konfigurasi yang mengutamakan CSS. Alih-alih file konfigurasi JavaScript, Anda menulis konfigurasi langsung sebagai CSS menggunakan direktif @theme.

JSON
{
  "tailwind": {
    "enabled": true,
    "config": "@theme { --color-primary: #3b82f6; --color-secondary: #10b981; --font-family-heading: 'Inter', sans-serif; }"
  }
}

Nilai config adalah string CSS yang ditambahkan setelah direktif @import "tailwindcss". Anda dapat menggunakan sintaks Tailwind v4 CSS valid apa pun di sini:

JSON
{
  "tailwind": {
    "enabled": true,
    "config": "@theme { --color-brand: oklch(0.7 0.15 200); } @layer base { h1 { font-size: var(--text-4xl); } }"
  }
}

Untuk konfigurasi beberapa baris, pendekatan filter lebih praktis:

PHP
add_filter('blockstudio/settings/tailwind/config', function () {
    return <<<CSS
@theme {
    --color-primary: #3b82f6;
    --color-secondary: #10b981;
    --font-family-heading: 'Inter', sans-serif;
    --breakpoint-xs: 30rem;
}

@layer base {
    body {
        font-family: var(--font-family-sans);
    }
}

@layer utilities {
    .btn { @apply px-4 py-2 rounded-lg font-medium; }
    .btn-primary { @apply bg-blue-500 text-white hover:bg-blue-600; }
    .card { @apply bg-white rounded-xl shadow-lg p-6; }
}
CSS;
});

Kelas Utility Kustom

Untuk mendefinisikan alias kelas yang dapat digunakan kembali, gunakan @layer utilities dengan direktif @apply milik Tailwind langsung dalam string konfigurasi Anda:

JSON
{
  "tailwind": {
    "enabled": true,
    "config": "@theme { --color-brand: #6366f1; } @layer utilities { .btn { @apply px-4 py-2 rounded-lg font-medium; } .section { @apply py-16 px-4 max-w-7xl mx-auto; } }"
  }
}

Ini mengompilasi kelas-kelas tersebut bersama semua utility Tailwind standar. Kelas ini berfungsi di frontend (kompilasi sisi server) maupun di editor (pratinjau CDN).

Blockstudio mempertahankan urutan lapisan cascade kanonis milik Tailwind: theme, base, components, lalu utilities. Ini sesuai dengan Tailwind CSS, sehingga aturan pada lapisan yang lebih akhir dapat menimpa lapisan sebelumnya sesuai harapan.

Jenis Field Kelas

Untuk menggunakan kelas Tailwind pada field classes sebuah blok dengan dukungan pelengkapan otomatis, atur tailwind: true pada field tersebut:

JSON
{
  "name": "my-theme/hero",
  "title": "Hero",
  "blockstudio": {
    "attributes": [
      {
        "id": "classes",
        "type": "classes",
        "label": "Classes",
        "tailwind": true,
        "default": "bg-white text-gray-900"
      }
    ]
  }
}

Saat tailwind bernilai true:

  • Field menyediakan saran pelengkapan otomatis dari daftar kelas lengkap Tailwind
  • Skrip Tailwind CDN dimuat di editor untuk pratinjau langsung
  • Kelas disimpan sebagai string yang dipisahkan spasi dalam atribut blok

Gunakan nilai kelas di templat Anda:

PHP
<div class="<?php echo $a['classes']; ?>">
  <!-- block content -->
</div>

Referensi Pengaturan

Opsi Jenis Default Deskripsi
enabled boolean false Aktifkan kompilasi Tailwind CSS di frontend
config string "" String konfigurasi Tailwind v4-first CSS

Mengatur melalui JSON

JSON
{
  "tailwind": {
    "enabled": true,
    "config": "@theme { --color-brand: pink; }"
  }
}

Mengatur melalui Filter

PHP
add_filter('blockstudio/settings/tailwind/enabled', '__return_true');

add_filter('blockstudio/settings/tailwind/config', function () {
    return '@theme { --color-brand: pink; }';
});

Caching

Blockstudio menggunakan strategi caching khusus yang dirancang untuk arsitektur berbasis utility milik Tailwind.

Cara Kerja Cache

Alih-alih melakukan hash pada seluruh HTML halaman (yang akan membatalkan cache pada setiap permintaan karena nonce, stempel waktu, dan konten dinamis lainnya), Blockstudio hanya mengekstrak kandidat kelas CSS dari HTML. Kandidat ini diurutkan dan di-hash bersama konfigurasi CSS untuk menghasilkan kunci cache yang stabil.

Artinya:

  • Dua halaman yang menggunakan kumpulan kelas Tailwind yang sama berbagi file CSS yang tersimpan dalam cache, meskipun HTML keduanya sepenuhnya berbeda
  • Konten dinamis seperti nonce, bilah pengguna yang masuk, jumlah komentar, dan stempel waktu tidak membatalkan cache
  • Cache hanya diinvalidasi saat kumpulan kelas CSS pada halaman berubah atau konfigurasi Tailwind berubah

Saat runtime menggunakan sumber penemuan logis, sumber yang dipilih dan konteks runtime juga menjadi bagian dari namespace cache. CSS terakhir yang berhasil diisolasi di antara pratinjau dan tidak dapat bocor dari satu pilihan sumber ke pilihan lainnya.

Lokasi Cache

File cache disimpan di:

Kode
wp-content/blockstudio/cache/sites/{network-blog}/{runtime-identity}/tailwind/

cache.path yang dikonfigurasi, identitas multisite saat ini, dan identitas runtime lengkap menentukan prefiks yang tepat. Setiap file diberi nama menggunakan hash MD5: {hash}.css.

Menghapus Cache

Hapus isi direktori cache untuk memaksa kompilasi ulang:

PHP
// Clear all cached Tailwind CSS
Blockstudio\Runtime_Cache::purge('tailwind');

Atau melalui WP-CLI:

Shell
wp eval "Blockstudio\\Runtime_Cache::purge('tailwind');"

Permintaan frontend berikutnya akan mengompilasi ulang dan menyimpan CSS ke cache secara otomatis.

Filter

blockstudio/tailwind/css

Ubah input CSS sebelum kompilasi. String input CSS diawali dengan @import "tailwindcss";, diikuti konfigurasi apa pun. Gunakan filter ini untuk menambahkan direktif CSS, aturan @layer kustom, atau impor plugin.

PHP
add_filter('blockstudio/tailwind/css', function (string $css): string {
    // Add a custom utility
    $css .= "\n@utility container-narrow { max-width: 48rem; margin-inline: auto; }";

    return $css;
});

Input CSS lengkap yang dikompilasi akan terlihat seperti ini:

CSS
/* Base import */
@import 'tailwindcss';

/* Config from settings (if set) */
@theme {
  --color-brand: pink;
}

/* Anything added via the blockstudio/tailwind/css filter */

Output Buffer

Kompilasi Tailwind terhubung ke sistem output buffer milik Blockstudio. Buffer menangkap HTML halaman lengkap setelah WordPress selesai merender, sehingga Tailwind dapat memindai semua kelas dari setiap sumber: templat blok, templat tema, output plugin, filter the_content, dan area widget.

Filter kompilasi berjalan pada prioritas 999999 di hook blockstudio/buffer/output, sehingga memproses HTML akhir setelah semua modifikasi lain. Buffer dimulai pada aksi template_redirect, sehingga hanya berjalan pada permintaan frontend, bukan di admin, REST API, atau konteks AJAX.

Pem-buffer-an seluruh dokumen memungkinkan hal ini, sehingga fitur tersebut aktif secara default. Situs yang tidak menggunakan Tailwind maupun aset blok dapat menonaktifkannya:

PHP
add_filter( 'blockstudio/buffer/enabled', '__return_false' );

Mengembalikan false melewati buffer sepenuhnya, yang juga menonaktifkan kompilasi Tailwind serta pemindahan gaya dan skrip blok ke dalam head dan footer.

Arsitektur

Kode
Frontend Request
  │
  ├─ WordPress renders HTML into output buffer
  │
  ├─ blockstudio/buffer/output filter (priority 999999)
  │   │
  │   ├─ Settings::get('tailwind/enabled') → false? Return HTML unchanged
  │   │
  │   ├─ build_css_input()
  │   │   ├─ @import "tailwindcss"
  │   │   ├─ + tailwind/config setting
  │   │   └─ + blockstudio/tailwind/css filter
  │   │
  │   ├─ TailwindPHP::extractCandidates($html)
  │   │   └─ Returns array of CSS class names found in HTML
  │   │
  │   ├─ Cache key = md5(sorted candidates + css input)
  │   │
  │   ├─ Cache hit?
  │   │   ├─ Yes → Read CSS from the shared runtime `tailwind/{hash}.css` scope
  │   │   └─ No  → TailwindPHP::generate() → Write to cache file
  │   │
  │   └─ Inject inline CSS, or link the content-hashed cache file when tailwind.output is "link"
  │
  └─ Browser receives HTML with compiled CSS


Editor Request
  │
  ├─ Admin loads block editor
  │
  ├─ Block with classes field (tailwind: true) detected
  │   └─ Block_Registry::set_tailwind_active(true)
  │
  ├─ Admin passes isTailwindActive + tailwindUrl to JS
  │
  └─ useTailwind() hook
      ├─ Injects Tailwind CDN script into document
      ├─ Creates hidden template div with HTML content
      ├─ Creates style tag for config
      └─ CDN compiles CSS in-browser for live preview

Contoh Lengkap

Penyiapan lengkap yang berfungsi dengan warna tema kustom dan blok yang menggunakannya:

JSON
{
  "$schema": "https://blockstudio.dev/schema/blockstudio",
  "tailwind": {
    "enabled": true,
    "config": "@theme { --color-brand: #6366f1; --color-brand-light: #a5b4fc; --color-surface: #f8fafc; } @layer utilities { .section-padding { @apply py-20 px-6; } .content-width { @apply max-w-5xl mx-auto; } .heading-xl { @apply text-4xl font-bold tracking-tight; } }"
  }
}
JSON
{
  "name": "my-theme/hero",
  "title": "Hero Section",
  "blockstudio": {
    "attributes": [
      {
        "id": "title",
        "type": "text",
        "label": "Title",
        "default": "Welcome"
      },
      {
        "id": "wrapperClasses",
        "type": "classes",
        "label": "Wrapper Classes",
        "tailwind": true,
        "default": "section-padding bg-surface"
      },
      {
        "id": "titleClasses",
        "type": "classes",
        "label": "Title Classes",
        "tailwind": true,
        "default": "heading-xl text-brand"
      }
    ]
  }
}
PHP
<section class="<?php echo $a['wrapperClasses']; ?>">
  <div class="content-width">
    <h1 class="<?php echo $a['titleClasses']; ?>">
      <?php echo esc_html($a['title']); ?>
    </h1>
  </div>
</section>

Ini dirender di frontend dengan semua utility Tailwind dan warna tema kustom dikompilasi ke dalam satu tag <style> sebaris.

Membangun Pustaka Blok

Token desain, utility kustom, dan penyiapan lengkap Tailwind v4 untuk tema produksi.