Vite Entegrasyonu

Nette Assets, Vite ile sorunsuz bir şekilde entegre olur, böylece şablonlarınızı her zamanki gibi yazarken tüm bu avantajlardan yararlanırsınız.

Vite Kurulumu

Vite'ı adım adım kuralım. Derleme araçlarına yeni başlıyorsanız endişelenmeyin – her şeyi açıklayacağız!

Adım 1: Vite'ı Kurun

Önce, Vite'ı ve Nette eklentisini projenize kurun:

npm install -D vite @nette/vite-plugin

Bu, Vite'ı ve Vite'ın Nette ile mükemmel çalışmasına yardımcı olan özel bir eklentiyi kurar.

Adım 2: Proje Yapısı

Standart yaklaşım, kaynak varlık dosyalarını proje kökünüzdeki bir assets/ klasörüne ve derlenmiş sürümlerini www/assets/'ye yerleştirmektir:

web-project/
├── assets/                   ← kaynak dosyalar (SCSS, TypeScript, kaynak görseller)
│   ├── public/               ← statik dosyalar (olduğu gibi kopyalanır)
│   │   └── favicon.ico
│   ├── images/
│   │   └── logo.png
│   ├── app.js                ← ana giriş noktası
│   └── style.css             ← stilleriniz
└── www/                      ← public dizini (belge kökü)
	├── assets/               ← derlenmiş dosyalar buraya gidecek
	└── index.php

assets/ klasörü, kaynak dosyalarınızı – yazdığınız kodu – içerir. Vite bu dosyaları işleyecek ve derlenmiş sürümlerini www/assets/'ye koyacaktır.

Adım 3: Vite'ı Yapılandırın

Proje kökünüzde bir vite.config.ts dosyası oluşturun. Bu dosya, Vite'a kaynak dosyalarınızı nerede bulacağını ve derlenmiş dosyaları nereye koyacağını söyler.

Nette Vite eklentisi, yapılandırmayı basitleştiren akıllı varsayılan ayarlarla gelir. Ön uç kaynak dosyalarınızın assets/ dizininde (root seçeneği) olduğunu ve derlenmiş dosyaların www/assets/'ye gittiğini (outDir seçeneği) varsayar. Yalnızca giriş noktasını belirtmeniz gerekir:

import { defineConfig } from 'vite';
import nette from '@nette/vite-plugin';

export default defineConfig({
	plugins: [
		nette({
			entry: 'app.js',
		}),
	],
});

Varlıklarınızı derlemek için başka bir dizin adı belirtmek isterseniz, birkaç seçeneği değiştirmeniz gerekecektir:

export default defineConfig({
	root: 'assets', // kaynak varlıkların kök dizini

	build: {
		outDir: '../www/assets',  // derlenmiş dosyaların gideceği yer
	},

	// ... diğer yapılandırma ...
});

outDir yolu, root'a göreli olarak kabul edilir, bu yüzden başında ../ vardır.

Adım 4: Nette'i Yapılandırın

common.neon dosyanızda Nette Assets'e Vite hakkında bilgi verin:

assets:
	mapping:
		default:
			type: vite      # Nette'e ViteMapper'ı kullanmasını söyler
			path: assets

Adım 5: Betikleri Ekleyin

Bu betikleri package.json dosyanıza ekleyin:

{
	"scripts": {
		"dev": "vite",
		"build": "vite build"
	}
}

Şimdi şunları yapabilirsiniz:

• npm run dev – sıcak yeniden yükleme ile geliştirme sunucusunu başlat
• npm run build – optimize edilmiş üretim dosyaları oluştur

Giriş Noktaları

Bir giriş noktası, uygulamanızın başladığı ana dosyadır. Bu dosyadan diğer dosyaları (CSS, JavaScript modülleri, görseller) içe aktararak bir bağımlılık ağacı oluşturursunuz. Vite bu içe aktarmaları takip eder ve her şeyi bir araya getirir.

Örnek giriş noktası assets/app.js:

// Stilleri içe aktar
import './style.css'

// JavaScript modüllerini içe aktar
import netteForms from 'nette-forms';
import naja from 'naja';

// Uygulamanızı başlat
netteForms.initOnLoad();
naja.initialize();

Şablonda bir giriş noktasını şu şekilde ekleyebilirsiniz:

{asset 'app.js'}

Nette Assets, tüm gerekli HTML etiketlerini (JavaScript, CSS ve diğer bağımlılıklar) otomatik olarak oluşturur.

Birden Çok Giriş Noktası

Daha büyük uygulamalar genellikle ayrı giriş noktalarına ihtiyaç duyar:

export default defineConfig({
	plugins: [
		nette({
			entry: [
				'app.js',      // public sayfalar
				'admin.js',    // yönetici paneli
			],
		}),
	],
});

Bunları farklı şablonlarda kullanın:

{* Public sayfalarda *}
{asset 'app.js'}

{* Yönetici panelinde *}
{asset 'admin.js'}

Önemli: Kaynak vs. Derlenmiş Dosyalar

Üretimde yalnızca şunları yükleyebileceğinizi anlamak çok önemlidir:

1. entry içinde tanımlanan Giriş noktaları
2. assets/public/ dizinindeki dosyalar

{asset} kullanarak assets/ içindeki rastgele dosyaları yükleyemezsiniz – yalnızca JavaScript veya CSS dosyaları tarafından referans verilen varlıkları yükleyebilirsiniz. Dosyanız hiçbir yerde referans verilmiyorsa derlenmeyecektir. Vite'ın diğer varlıklardan haberdar olmasını istiyorsanız, onları public klasörüne taşıyabilirsiniz.

Varsayılan olarak, Vite'ın 4KB'den küçük tüm varlıkları satır içine alacağını unutmayın, bu nedenle bu dosyalara doğrudan referans veremeyeceksiniz. (Bkz. Vite dokümantasyonu).

{* ✓ Bu çalışır - bir giriş noktasıdır *}
{asset 'app.js'}

{* ✓ Bu çalışır - assets/public/ içinde *}
{asset 'favicon.ico'}

{* ✗ Bu çalışmaz - assets/ içinde rastgele bir dosya *}
{asset 'components/button.js'}

Geliştirme Modu

Geliştirme modu tamamen isteğe bağlıdır ancak etkinleştirildiğinde önemli faydalar sağlar. Ana avantajı Hot Module Replacement (HMR)'dır – uygulama durumunu kaybetmeden anında değişiklikleri görün, bu da geliştirme deneyimini çok daha pürüzsüz ve hızlı hale getirir.

Vite, geliştirmeyi inanılmaz hızlı hale getiren modern bir derleme aracıdır. Geleneksel paketleyicilerin aksine, Vite geliştirme sırasında kodunuzu doğrudan tarayıcıya sunar, bu da projenizin ne kadar büyük olursa olsun anında sunucu başlangıcı ve ışık hızında güncellemeler anlamına gelir.

Geliştirme Sunucusunu Başlatma

Geliştirme sunucusunu çalıştırın:

npm run dev

Şunları göreceksiniz:

  ➜  Local:   http://localhost:5173/
  ➜  Network: use --host to expose

Geliştirme yaparken bu terminali açık tutun.

Nette Vite eklentisi otomatik olarak şunları algılar:

1. Vite geliştirme sunucusu çalışıyor
2. Nette uygulamanız hata ayıklama modunda

Her iki koşul da karşılandığında, Nette Assets dosyaları derlenmiş dizin yerine Vite geliştirme sunucusundan yükler:

{asset 'app.js'}
{* Geliştirmede: <script src="http://localhost:5173/app.js" type="module"></script> *}
{* Üretimde: <script src="/assets/app-4a8f9c7.js" type="module"></script> *}

Yapılandırmaya gerek yok – sadece çalışır!

Farklı Alan Adlarında Çalışma

Geliştirme sunucunuz localhost dışında bir şey üzerinde çalışıyorsa (örneğin myapp.local), CORS (Cross-Origin Resource Sharing) sorunlarıyla karşılaşabilirsiniz. CORS, web tarayıcılarında varsayılan olarak farklı alan adları arasındaki istekleri engelleyen bir güvenlik özelliğidir. PHP uygulamanız myapp.local üzerinde çalışırken Vite localhost:5173 üzerinde çalıştığında, tarayıcı bunları farklı alan adları olarak görür ve istekleri engeller.

Bu sorunu çözmek için iki seçeneğiniz var:

Seçenek 1: CORS'u Yapılandırın

En basit çözüm, PHP uygulamanızdan çapraz kaynak isteklerine izin vermektir:

export default defineConfig({
	// ... diğer yapılandırma ...

	server: {
		cors: {
			origin: 'http://myapp.local',  // PHP uygulamanızın URL'si
		},
	},
});

Seçenek 2: Vite'ı alan adınızda çalıştırın

Diğer çözüm, Vite'ı PHP uygulamanızla aynı alan adında çalıştırmaktır.

export default defineConfig({
	// ... diğer yapılandırma ...

	server: {
		host: 'myapp.local',  // PHP uygulamanızla aynı
	},
});

Aslında, bu durumda bile CORS'u yapılandırmanız gerekir çünkü geliştirme sunucusu aynı ana bilgisayar adında ancak farklı bir bağlantı noktasında çalışır. Ancak, bu durumda CORS, Nette Vite eklentisi tarafından otomatik olarak yapılandırılır.

HTTPS Geliştirme

HTTPS üzerinde geliştirme yapıyorsanız, Vite geliştirme sunucunuz için sertifikalara ihtiyacınız vardır. En kolay yol, sertifikaları otomatik olarak oluşturan bir eklenti kullanmaktır:

npm install -D vite-plugin-mkcert

İşte vite.config.ts'de nasıl yapılandırılacağı:

import mkcert from 'vite-plugin-mkcert';

export default defineConfig({
	// ... diğer yapılandırma ...

	plugins: [
		mkcert(),  // sertifikaları otomatik olarak oluşturur ve https'yi etkinleştirir
		nette(),
	],
});

CORS yapılandırmasını (yukarıdaki Seçenek 1) kullanıyorsanız, kaynak URL'yi http:// yerine https:// kullanacak şekilde güncellemeniz gerektiğini unutmayın.

Üretim Derlemeleri

Optimize edilmiş üretim dosyaları oluşturun:

npm run build

Vite şunları yapacaktır:

• Tüm JavaScript ve CSS'yi küçültür
• Kodu optimal parçalara böler
• Önbellek temizleme için karma adlandırılmış dosyalar oluşturur
• Nette Assets için bir manifest dosyası oluşturur

Örnek çıktı:

www/assets/
├── app-4f3a2b1c.js       # Ana JavaScript'iniz (küçültülmüş)
├── app-7d8e9f2a.css      # Çıkarılan CSS (küçültülmüş)
├── vendor-8c4b5e6d.js    # Paylaşılan bağımlılıklar
└── .vite/
	└── manifest.json     # Nette Assets için eşleştirme

Karma adlandırılmış dosyalar, tarayıcıların her zaman en son sürümü yüklemesini sağlar.

Public Klasörü

assets/public/ dizinindeki dosyalar, işlenmeden çıktı dizinine kopyalanır:

assets/
├── public/
│   ├── favicon.ico
│   ├── robots.txt
│   └── images/
│       └── og-image.jpg
├── app.js
└── style.css

Onlara normal şekilde referans verin:

{* Bu dosyalar olduğu gibi kopyalanır *}
<link rel="icon" href={asset 'favicon.ico'}>
<meta property="og:image" content={asset 'images/og-image.jpg'}>

Public dosyalar için FilesystemMapper özelliklerini kullanabilirsiniz:

assets:
	mapping:
		default:
			type: vite
			path: assets
			extension: [webp, jpg, png]  # Önce WebP'yi dene
			versioning: true             # Önbellek temizleme ekle

vite.config.ts yapılandırmasında publicDir seçeneğini kullanarak public klasörünü değiştirebilirsiniz.

Dinamik İçe Aktarmalar

Vite, optimal yükleme için kodu otomatik olarak böler. Dinamik içe aktarmalar, kodu yalnızca gerçekten ihtiyaç duyulduğunda yüklemenize olanak tanır, bu da başlangıç paketi boyutunu azaltır:

// Ağır bileşenleri talep üzerine yükle
button.addEventListener('click', async () => {
	let { Chart } = await import('./components/chart.js')
	new Chart(data)
})

Dinamik içe aktarmalar, yalnızca gerektiğinde yüklenen ayrı yığınlar oluşturur. Buna “kod bölme” denir ve Vite'ın en güçlü özelliklerinden biridir. Dinamik içe aktarmaları kullandığınızda, Vite her dinamik olarak içe aktarılan modül için otomatik olarak ayrı JavaScript dosyaları oluşturur.

{asset 'app.js'} etiketi bu dinamik yığınları otomatik olarak ön yüklemez. Bu kasıtlı bir davranıştır – asla kullanılmayabilecek kodu indirmek istemeyiz. Yığınlar yalnızca dinamik içe aktarma yürütüldüğünde indirilir.

Ancak, belirli dinamik içe aktarmaların kritik olduğunu ve yakında ihtiyaç duyulacağını biliyorsanız, bunları ön yükleyebilirsiniz:

{* Ana giriş noktası *}
{asset 'app.js'}

{* Kritik dinamik içe aktarmaları ön yükle *}
{preload 'components/chart.js'}

Bu, tarayıcıya grafik bileşenini arka planda indirmesini söyler, böylece ihtiyaç duyulduğunda hemen hazır olur.

TypeScript Desteği

TypeScript kutudan çıktığı gibi çalışır:

// assets/main.ts
interface User {
	name: string
	email: string
}

export function greetUser(user: User): void {
	console.log(`Merhaba, ${user.name}!`)
}

TypeScript dosyalarına normal şekilde referans verin:

{asset 'main.ts'}

Tam TypeScript desteği için kurun:

npm install -D typescript

Ek Vite Yapılandırması

İşte ayrıntılı açıklamalarla bazı kullanışlı Vite yapılandırma seçenekleri:

export default defineConfig({
	// Kaynak varlıkları içeren kök dizin
	root: 'assets',

	// İçeriği çıktı dizinine olduğu gibi kopyalanan klasör
	// Varsayılan: 'public' ('root'a göreli)
	publicDir: 'public',

	build: {
		// Derlenmiş dosyaları nereye koymalı ('root'a göreli)
		outDir: '../www/assets',

		// Derlemeden önce çıktı dizinini boşaltmalı mı?
		// Önceki derlemelerden kalan eski dosyaları kaldırmak için kullanışlıdır
		emptyOutDir: true,

		// Oluşturulan yığınlar ve varlıklar için outDir içindeki alt dizin
		// Bu, çıktı yapısını düzenlemeye yardımcı olur
		assetsDir: 'static',

		rollupOptions: {
			// Giriş noktası/noktaları - tek bir dosya veya dosya dizisi olabilir
			// Her giriş noktası ayrı bir paket haline gelir
			input: [
				'app.js',      // ana uygulama
				'admin.js',    // yönetici paneli
			],
		},
	},

	server: {
		// Geliştirme sunucusunu bağlamak için ana bilgisayar
		// Ağa açmak için '0.0.0.0' kullanın
		host: 'localhost',

		// Geliştirme sunucusu için bağlantı noktası
		port: 5173,

		// Çapraz kaynak istekleri için CORS yapılandırması
		cors: {
			origin: 'http://myapp.local',
		},
	},

	css: {
		// Geliştirmede CSS kaynak haritalarını etkinleştir
		devSourcemap: true,
	},

	plugins: [
		nette(),
	],
});

Hepsi bu kadar! Artık Nette Assets ile entegre modern bir derleme sisteminiz var.