CSS, JS ve derleme

Bu sayfa, CSS ve JavaScript'i nasıl derleyeceğinizi ve Acun UI'nin bu dosyaları sayfalara nasıl yüklediğini anlatır.

Derlemek

Tasarımı değiştirdiğinizde CSS ve JavaScript'i yeniden derleyin:

npm install        # yalnızca ilk seferde: Vite ve Tailwind derleme araçlarını kurar
npm run build      # canlı ortam için derler (public/build)

Derlenmiş dosyalar temanın zip'inde hazır gelir. Şu durumlarda yeniden derleyin:

• renkleri ya da @theme ayarlarını değiştirdiniz,
• Blade dosyalarına yeni Tailwind sınıfları yazdınız,
• resources/js altındaki dosyaları değiştirdiniz,
• Acun UI paketlerini güncellediniz.

npm install yalnızca derleme araçlarını kurar. Acun UI'nin kendisi npm'den gelmez: package.json içindeki "@acunsoft/acun-ui-core": "file:packages/acun-ui/acun-ui-core" satırı zip'teki klasörü kullanır. Sunucuya yüklemeden önce yapılacaklar Yayına alma sayfasındadır.

Geliştirme sunucusu

Geliştirirken her değişiklikte yeniden derlemek yerine Vite'ın geliştirme sunucusunu çalıştırın:

npm run dev

CSS ve JavaScript değişiklikleri anında görünür. Blade dosyaları ya da menü değişince sayfa kendiliğinden yenilenir. composer run dev sunucuyu, kuyruğu ve Vite'ı birlikte başlatır.

Geliştirme sunucusunu kapatınca sayfalar yeniden public/build içindeki derlenmiş dosyaları kullanır.

Her sayfada yüklenen dosyalar

Hazır düzenler her sayfanın <head> bölümünde üç dosya yükler:

@vite(['resources/css/acun-ui.css', 'resources/js/acun-ui.js', 'resources/js/app.js'])

Aynı üç dosya vite.config.js içindeki input listesindedir. Kendi düzeninizde de bu sırayla yükleyin. Mevcut bir projede CSS dosyasının adı genellikle resources/css/app.css'tir; işleyiş aynıdır.

CSS dosyası

CSS dosyası Tailwind'i, Acun UI'nin temasını ve bileşenlerin stillerini bir araya getirir:

@import 'tailwindcss';
@plugin '@tailwindcss/forms';
@import '@acunsoft/acun-ui-core';
@import '../../vendor/acunsoft/acun-ui-pro/resources/css/acun-ui-pro.css';

@source '../../vendor/acunsoft/acun-ui-free/resources/views';
@source '../../vendor/acunsoft/acun-ui-pro/resources/views';

• @import '@acunsoft/acun-ui-core' temayı, düzeni ve menüyü getirir.
• acun-ui-pro.css DataTable ve form penceresi stillerini ekler.
• @source satırları Tailwind'e paketlerin Blade dosyalarını taratır. Onlar olmazsa bileşenlerin sınıfları derlemeye girmez ve bileşenler stilsiz görünür.

Full sürümde dosya ayrıca front.css'i içe aktarır: önyüz temalarının yazı tipi, köşe ve yüzey kuralları. Renkleri ve görünümü değiştirmek için Özelleştirme sayfasına bakın.

JavaScript katmanları

Acun UI'nin JavaScript'i katmanlara ayrılır; böylece her sayfa yalnızca gerekeni indirir.

resources/js/acun-ui.js iki satırdır:

import '@acunsoft/acun-ui-core';
import '@acunsoft/acun-ui-pro';

Acun UI ayrı bir dosyada olduğu için uygulamanızın kodu değişince tarayıcı onu yeniden indirmez. app.js Acun UI'yi içe aktarmaz; aksi hâlde Vite iki giriş için ortak bir parça çıkarır. PRO'nun kayıt işlevleri bu yüzden window.AcunUI.pro altındadır. Alpine, Livewire ile gelir; ayrıca kurmanız gerekmez.

import '@acunsoft/acun-ui-core' olmadan çekmece ve pencere açılmaz, görünüm ayarları çalışmaz. Panel düzeni kullanan her sayfa ona ihtiyaç duyar.

@acunsoft/acun-ui-pro bir npm paketi değildir. vite.config.js içindeki takma ad onu Composer paketinden bulur:

resolve: {
    alias: { '@acunsoft/acun-ui-pro': path.resolve(import.meta.dirname, 'vendor/acunsoft/acun-ui-pro/resources/js/index.js') },
},

Ağır bileşenler yalnızca gerektiğinde

Büyük bileşenlerin JavaScript'i yalnızca sayfada o bileşen varken iner. Örneğin DataTable'ın tarayıcı tarafı (dışa aktarma, tam ekran, sabit başlık ve sütunlar), combobox, dosya yükleme ve form penceresi ayrı parçalardır.

<!-- acun:combobox'ın sunucuda çizdiği HTML -->
<div x-data="uiCombobox" data-acun-component="combobox">…</div>

Bileşen sunucunun HTML'ine data-acun-component="…" işaretini koyar. Bu işaretli bir eleman sayfada ilk kez göründüğünde Acun UI bileşenin parçasını bir kez indirir. Alpine o elemanı parça gelince başlatır.

• İlk açılışta, wire:navigate geçişinde, Livewire'ın sonradan eklediği elemanlarda ve iç içe Livewire bileşenlerinde aynı şekilde çalışır. Sayfa ayrıca taranmaz.
• Aynı sayfadaki beş combobox için parça bir kez iner.
• Parça gelene kadar bileşenin sunucuda çizilen HTML'i görünür.
• Tarayıcı işlemi olmayan bir DataTable hiç JavaScript indirmez.
• Parça inemezse konsolda [Acun UI] The JavaScript of the "combobox" component could not be loaded. hatası çıkar.

Parçayı önceden indirmek

Kullanıcının birazdan açacağı bir pencere için parçayı önceden indirebilirsiniz:

AcunUI.load('combobox');

Kendi bileşeninizi eklemek

Kendi ağır bileşeninizi aynı düzene katmak için onu bir adla tanımlayın:

window.AcunUI.components.define('editor', () => import('./components/editor.js').then((module) => module.register(window.Alpine)));

<div data-acun-component="editor" x-data="editor(@js($ayarlar))">…</div>

PRO'nun registerCombobox, registerFileUpload, registerDataTable, registerDataTableFixed ve registerFormModal işlevleri önce bileşenin parçasını indirir ve bir Promise döndürür. Bunları eskisi gibi çağırmaya devam edebilirsiniz. Kaydedilmemiş değişiklik yöneticisinin API'si için: const { initDirtyForms } = await loadDirtyForms();.

Sayfaya özel kod

Yalnızca bir sayfanın ihtiyacı olan JavaScript'i o sayfada yükleyin:

@push('page-scripts')
    @vite('resources/js/pages/rapor.js')
@endpush

Hazır düzenler </body> öncesinde @stack('page-scripts') yazar. Dosyayı vite.config.js içindeki input listesine de ekleyin.

Tekrar kullanılan davranışı (tablo, pencere) buraya değil bileşene koyun; sayfa kodu yalnızca o sayfanın işini yapsın. wire:navigate ile aynı sayfaya dönüldüğünde modül yeniden çalışmaz. Her girişte çalışacak kodu document.addEventListener('livewire:navigated', …) içine yazın.

Grafik, harita ve tarih aralığı

Grafik, harita ve tarih aralığı bileşenleri dış kütüphane kullanır: ApexCharts, Leaflet ve flatpickr. Kütüphaneleri uygulamanız Acun UI'ye verir. resources/js/app.js içinde:

document.addEventListener('livewire:init', () => {
    const { lazyLibrary, registerChart, registerDateRangePicker, registerMap } = window.AcunUI.pro;

    registerChart(window.Alpine, lazyLibrary(() => import('apexcharts')));

    registerMap(window.Alpine, lazyLibrary(() => import('leaflet/dist/leaflet.css').then(() => import('leaflet'))));

    // Takvim sayfanın dilinde: Türkçe sayfada Türkçe ay ve gün adları.
    registerDateRangePicker(window.Alpine, lazyLibrary(async () => {
        const turkish = document.documentElement.lang.startsWith('tr');
        const [{ default: flatpickr }, locale] = await Promise.all([
            import('flatpickr'),
            turkish ? import('flatpickr/dist/l10n/tr.js') : Promise.resolve(null),
            import('flatpickr/dist/flatpickr.min.css'),
        ]);
        if (locale) flatpickr.localize(locale.Turkish);

        return flatpickr;
    }));
});

lazyLibrary kütüphaneyi uygulamanın JavaScript'ine katmaz. Kütüphane ayrı bir parça olarak, yalnızca o bileşenin bulunduğu sayfada ve ilk kullanıldığında stiliyle birlikte iner. ApexCharts tek başına yaklaşık 530 kB'tır; grafiği olmayan sayfalar onu hiç indirmez.

Kütüphaneyi doğrudan da verebilirsiniz: registerChart(window.Alpine, ApexCharts). O zaman kütüphane uygulamanın JavaScript'iyle birlikte her sayfada gelir.

Parçalara adlarını vermek için (apexcharts-*.js, leaflet-*.js, flatpickr-*.js) vite.config.js içine şunu ekleyin:

build: {
    rolldownOptions: {
        output: {
            codeSplitting: {
                groups: [
                    { name: 'apexcharts', test: /node_modules[\\/]apexcharts[\\/]/ },
                    { name: 'leaflet', test: /node_modules[\\/]leaflet[\\/]/ },
                    { name: 'flatpickr', test: /node_modules[\\/]flatpickr[\\/]/ },
                ],
            },
        },
    },
    // apexcharts-*.js kütüphanenin kendisidir ve yalnızca grafikli sayfada indirilir.
    chunkSizeWarningLimit: 600,
},

Dikkat

Harita varsayılan olarak OpenStreetMap'in ücretsiz karo sunucusunu kullanır. Bu sunucu yoğun canlı trafiğe izin vermez. Canlıda kendi karo sağlayıcınızı registerMap(Alpine, L, { tileUrl, attribution }) ile verin.

Yazı tipleri

Tema metin için Public Sans, kod ve sayısal etiketler için DM Mono yazı tipini kullanır. İkisini vite.config.js içinden yükleyin:

import { bunny } from 'laravel-vite-plugin/fonts';
import { woff2Only } from '@acunsoft/acun-ui-core/vite';

plugins: [
    laravel({
        input: ['resources/css/acun-ui.css', 'resources/js/acun-ui.js', 'resources/js/app.js'],
        fonts: [
            bunny('Public Sans', { weights: [400, 500, 600, 700], subsets: ['latin', 'latin-ext'], preload: [{ weight: 400 }, { weight: 600 }] }),
            bunny('DM Mono', { weights: [400, 500], subsets: ['latin', 'latin-ext'], preload: false }),
        ],
    }),
    woff2Only(),
    tailwindcss(),
],

Ardından düzenin head slot'una font etiketlerini ekleyin:

@acunFonts(['public-sans', 'dm-mono'])

latin-ext alt kümesi Türkçe harfleri (ş, ğ, İ, ı) içerir.

woff2Only

woff2Only() font derlemesinde yalnızca WOFF2 dosyalarını bırakır; onu laravel()'dan sonra yazın. Font sağlayıcıları her yüzü WOFF2 ve WOFF olarak gönderir. Eklenti ikisini aynı tanımlı iki ayrı @font-face kuralı olarak yazar ve WOFF'u sona koyar. Tarayıcı sonuncuyu kullandığı için daha büyük WOFF dosyalarını indirir; önceden yüklenen WOFF2'ler boşa gider. Acun UI'nin desteklediği her tarayıcı WOFF2 okur. woff2Only() WOFF dosyalarını, onların kurallarını ve manifest kayıtlarını çıkarır.

Önceden yükleme

preload yalnızca ilk ekranda hemen gereken ağırlıkları önceden yükletir: gövde metni için 400, başlık ve düğmeler için 600. Her ağırlık iki dosyadır (latin ve latin-ext); bu yüzden sayfaya dört font önyüklemesi düşer. Diğer ağırlıklar ve DM Mono kullanıldıkları anda gelir (font-display: swap).

preload verilmezse her ağırlık ve alt küme önceden yüklenir; bu yapılandırmada 12 dosya. Tarayıcı bunların çoğunu ilk ekranda kullanmaz ve "preloaded but not used" uyarısı verir.

@acunFonts

@acunFonts, Laravel'in @fonts yönergesiyle aynı önyükleme etiketlerini basar. Farkı şudur: @font-face kurallarını her sayfaya satır içi <style> olarak yazmaz; eklentinin derlediği fonts-*.css dosyasını bağlar. Tarayıcı bu dosyayı önbelleğe alır.

Birden çok font ailesi tanımladıysanız her düzen yalnızca kendi ailelerini yazabilir. Full sürümün önyüz temaları böyle yapar:

{{-- layouts/front/theme-3.blade.php: başlıklarda Fraunces --}}
@acunFonts(['public-sans', 'fraunces', 'dm-mono'])

Önyükleme etiketleri yalnızca o aileler için basılır; bağlanan dosya yine aynıdır. Tarayıcı sayfanın kullanmadığı fontu indirmez.

• Vite geliştirme sunucusu çalışırken @acunFonts tam olarak @fonts gibi davranır.
• Laravel 13'ten önceki sürümlerde @acunFonts hiçbir şey yazmaz; fontları o zaman kendi CSS'inizle yükleyin.
• Kendi font dosyalarınızı kullanıyorsanız @theme içinde --font-sans ve --font-mono değerlerini değiştirin.

Vite olmadan yüklemek

Vite kullanmıyorsanız JavaScript'in paketlerle gelen derlenmiş kopyalarını @acunUiScripts yönergesiyle yükleyin. Panel düzenlerinde onu head slot'una koyun:

<acun:layout.sidebar brand-name="Uygulamam">
    <acun:slot:head>
        @acunUiScripts
    </acun:slot:head>

    {{ $slot }}
</acun:layout.sidebar>

Yönerge ücretsiz acunsoft/acun-ui-free paketindedir. Önce Acun UI'nin ortak JavaScript'ini (acun-ui.js), PRO paketi kuruluysa ardından PRO JavaScript'ini (acun-ui-pro.js) yazar. Kendi düzeninizde onu <head> içine ya da </body> öncesine koyabilirsiniz. Etiketler defer ile gelir ve Livewire Alpine'ı başlatmadan önce çalışır; başka bir şey eklemeniz gerekmez.

• Dosyalar: paketlerin dist/ klasöründedir (acun-ui-free/dist/acun-ui.js, acun-ui-pro/dist/acun-ui-pro.js). Derleme adımı gerekmez. Paketler onları /acun-ui/acun-ui.js?id=<içerik özeti> ve /acun-ui/acun-ui-pro.js?id=<içerik özeti> adreslerinden bir yıllık önbellekle sunar. Dosya değişince adres de değişir.
• Adres ayarları: config/acun-ui.php içindedir. Ortak JavaScript için assets.prefix adresin önekidir (varsayılan acun-ui), assets.url dosyaların bulunduğu bir CDN klasörüdür. PRO için aynı ayarlar pro.assets.prefix ve pro.assets.url adını taşır; burada url dosyanın tam adresidir. Bkz. Yapılandırma.
• Web sunucusundan sunmak: dosyaları yayınlayın: php artisan vendor:publish --tag=acun-ui-assets (public/vendor/acun-ui), PRO için --tag=acun-ui-pro-assets (public/vendor/acun-ui-pro). Yönerge o zaman bu kopyaları kullanır. Paketi güncelledikten sonra --force ile yeniden yayınlayın. Ortak JavaScript'in eski kalan kopyası kullanılmaz, paketin kendi dosyası yüklenir. PRO'nun eski kalan kopyası için konsolda uyarı çıkar.
• Grafik, harita ve tarih aralığı: ApexCharts, Leaflet ve flatpickr'i <script> etiketiyle (async olmadan) yüklerseniz acun:chart, acun:map ve tarih aralığı seçici kendiliğinden kaydedilir. flatpickr'in dili sayfanın lang özniteliğinden seçilir. Kendi ayarlarınızla kaydetmek için livewire:init içinde window.AcunUI.pro.registerMap(window.Alpine, L, { tileUrl, attribution }) çağırın.
• Vite ile birlikte: uygulama JavaScript'i Acun UI'yi zaten Vite ile yüklüyorsa (import '@acunsoft/acun-ui-core', import '@acunsoft/acun-ui-pro') yönergenin dosyaları hiçbir şey yapmaz. Yine de ikisinden birini seçin.

Tema dosyası

Tema dosyası, kullanıcının tema, ana renk ve menü seçimlerini sayfa ekrana çizilmeden önce uygular; böylece sayfa açılırken renk değiştirip titremez. acun:layout.head onu <head> içine kendisi yazar (hazır düzenler bu bileşeni zaten kullanır):

<script type="application/json" data-acun-ui-config>{…}</script>
<script src="/acun-ui/acun-ui-boot.js?id=…" data-acun-ui-boot data-navigate-track></script>

Bu dosya defer almaz, çünkü ilk çizimden önce çalışmalıdır. Paketle gelir ve adresinde içerik özeti (?id=…) olduğu için tarayıcı onu bir yıl önbellekte tutar. Düzen satır içi JavaScript yazmaz; ayarlar data-acun-ui-config etiketinde yalnızca veri olarak gelir.

İçerik Güvenliği Politikası

Siteniz İçerik Güvenliği Politikası (CSP) kullanıyorsa Acun UI'nin JavaScript etiketlerine nonce verin:

@acunUiScripts(['nonce' => $nonce])
<acun:layout.head :nonce="$nonce">…</acun:layout.head>

Nonce verilmezse ikisi de Vite::cspNonce() değerini kullanır. Hazır düzenler nonce'u buradan alır; Laravel'de Vite::useCspNonce() ile bir nonce üretmeniz yeterlidir.

Ortak JavaScript yüklenmezse

Bir panel sayfasında import '@acunsoft/acun-ui-core' ya da @acunUiScripts yoksa tema dosyası tarayıcı konsoluna tek bir hata yazar (ileti İngilizcedir):

[Acun UI] JavaScript is not loaded: add "import '@acunsoft/acun-ui-core';" to resources/js/app.js and build the assets (npm run build), or add @acunUiScripts to your layout. Drawers, modals and the theme settings will not work.

Sayfa kayıtlı görünümüyle açılır ve başka bir hata çıkmaz. Ama çekmece ve pencere açılmaz; tema ve menü ayarları değişmez. Çözüm: import '@acunsoft/acun-ui-core' satırını JavaScript girişinize (temada resources/js/acun-ui.js) ekleyip derleyin ya da düzene @acunUiScripts ekleyin.

PRO JavaScript yüklenmezse

PRO JavaScript'ine ihtiyaç duyan bileşenler sayfaya bir kez küçük bir denetim ekler. Bu bileşenler: acun:combobox, acun:file-upload, acun:form-modal, acun:form dirty-check ve tarayıcı işlemi, sabit başlığı ya da sabit sütunları olan DataTable. PRO JavaScript'i yüklenmemişse konsolda şu hata çıkar:

[Acun UI PRO] JavaScript is not loaded: add "import '@acunsoft/acun-ui-pro';" to resources/js/app.js and build the assets (npm run build), or add @acunUiScripts to your layout. Components that will not work: acun:combobox (1), acun:data-table (1).

• İlk sayfa yüklemesinde açılır liste ve dosya yükleme alanı soluk ve tıklanamaz kalır. Sayfanın geri kalanı çalışır.
• DataTable'da arama, filtre ve sayfalama çalışmaya devam eder. Dışa aktarma, kopyalama ve tam ekran gibi tarayıcıdaki işlemler çalışmaz.
• @acunUiScripts sayfada olduğu hâlde dosya gelmediyse hata "The JavaScript file could not be loaded (…)" diye başlar.

Ayrıntılar: Sık sorulan sorular.

Daha fazlası

• Mevcut projeye ekleme: bu dosyaları sıfırdan kurmak.
• Bağımlılıklar: paketlerin ve kütüphanelerin listesi.
• Yapılandırma: config/acun-ui.php ayarları.
• Yayına alma: sunucuya yüklemeden önce derlemek.