Integrácia Vite

Nette Assets sa bezproblémovo integruje s Vite, takže získate všetky tieto výhody, zatiaľ čo svoje šablóny píšete ako obvykle.

Nastavenie Vite

Poďme nastaviť Vite krok za krokom. Nebojte sa, ak ste nováčik v build nástrojoch – všetko vysvetlíme!

Krok 1: Inštalácia Vite

Najprv nainštalujte Vite a Nette plugin do vášho projektu:

npm install -D vite @nette/vite-plugin

Tým sa nainštaluje Vite a špeciálny plugin, ktorý pomáha Vite perfektne fungovať s Nette.

Krok 2: Štruktúra projektu

Štandardný prístup je umiestniť zdrojové súbory assetov do priečinka assets/ v koreni vášho projektu a kompilované verzie do www/assets/:

web-project/
├── assets/                   ← zdrojové súbory (SCSS, TypeScript, zdrojové obrázky)
│   ├── public/               ← statické súbory (kopírované tak, ako sú)
│   │   └── favicon.ico
│   ├── images/
│   │   └── logo.png
│   ├── app.js                ← hlavný vstupný bod
│   └── style.css             ← vaše štýly
└── www/                      ← verejný adresár (document root)
	├── assets/               ← sem pôjdu kompilované súbory
	└── index.php

Priečinok assets/ obsahuje vaše zdrojové súbory – kód, ktorý píšete. Vite spracuje tieto súbory a umiestni kompilované verzie do www/assets/.

Krok 3: Konfigurácia Vite

Vytvorte súbor vite.config.ts v koreni vášho projektu. Tento súbor hovorí Vite, kde nájsť vaše zdrojové súbory a kam umiestniť kompilované súbory.

Nette Vite plugin prichádza s inteligentnými predvolenými nastaveniami, ktoré zjednodušujú konfiguráciu. Predpokladá, že vaše front-end zdrojové súbory sú v adresári assets/ (možnosť root) a kompilované súbory idú do www/assets/ (možnosť outDir). Potrebujete špecifikovať iba vstupný bod:

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

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

Ak chcete špecifikovať iný názov adresára pre build vašich assetov, budete musieť zmeniť niekoľko možností:

export default defineConfig({
	root: 'assets', // koreňový adresár zdrojových assetov

	build: {
		outDir: '../www/assets',  // kam idú kompilované súbory
	},

	// ... iná konfigurácia ...
});

Cesta outDir sa považuje za relatívnu k root, preto je na začiatku ../.

Krok 4: Konfigurácia Nette

Povedzte Nette Assets o Vite vo vašom common.neon:

assets:
	mapping:
		default:
			type: vite      # hovorí Nette, aby použilo ViteMapper
			path: assets

Krok 5: Pridajte skripty

Pridajte tieto skripty do vášho package.json:

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

Teraz môžete:

• npm run dev – spustiť vývojový server s hot reloadingom
• npm run build – vytvoriť optimalizované produkčné súbory

Vstupné body

Vstupný bod je hlavný súbor, kde sa spúšťa vaša aplikácia. Z tohto súboru importujete ďalšie súbory (CSS, JavaScript moduly, obrázky), čím vytvárate strom závislostí. Vite sleduje tieto importy a všetko zbalí dohromady.

Príklad vstupného bodu assets/app.js:

// Import štýlov
import './style.css'

// Import JavaScript modulov
import netteForms from 'nette-forms';
import naja from 'naja';

// Inicializujte vašu aplikáciu
netteForms.initOnLoad();
naja.initialize();

V šablóne môžete vložiť vstupný bod nasledovne:

{asset 'app.js'}

Nette Assets automaticky generuje všetky potrebné HTML tagy – JavaScript, CSS a akékoľvek iné závislosti.

Viacero vstupných bodov

Väčšie aplikácie často potrebujú samostatné vstupné body:

export default defineConfig({
	plugins: [
		nette({
			entry: [
				'app.js',      // verejné stránky
				'admin.js',    // administrátorský panel
			],
		}),
	],
});

Použite ich v rôznych šablónach:

{* Na verejných stránkach *}
{asset 'app.js'}

{* V administrátorskom paneli *}
{asset 'admin.js'}

Dôležité: Zdrojové vs. kompilované súbory

Je kľúčové pochopiť, že v produkcii môžete načítať iba:

1. Vstupné body definované v entry
2. Súbory z adresára assets/public/

Nemôžete načítať pomocou {asset} ľubovoľné súbory z assets/ – iba assets odkazované JavaScriptovými alebo CSS súbormi. Ak váš súbor nie je nikde odkazovaný, nebude skompilovaný. Ak chcete, aby Vite vedelo o iných assets, môžete ich presunúť do verejného priečinka.

Upozorňujeme, že predvolene Vite vloží všetky assets menšie ako 4KB, takže tieto súbory nebudete môcť odkazovať priamo. (Pozri dokumentáciu Vite).

{* ✓ Toto funguje - je to vstupný bod *}
{asset 'app.js'}

{* ✓ Toto funguje - je to v assets/public/ *}
{asset 'favicon.ico'}

{* ✗ Toto nebude fungovať - náhodný súbor v assets/ *}
{asset 'components/button.js'}

Vývojový režim

Vývojový režim je úplne voliteľný, ale pri jeho povolením poskytuje značné výhody. Hlavnou výhodou je Hot Module Replacement (HMR) – okamžité zobrazenie zmien bez straty stavu aplikácie, čo robí vývoj oveľa plynulejším a rýchlejším.

Vite je moderný build nástroj, ktorý robí vývoj neuveriteľne rýchlym. Na rozdiel od tradičných bundlerov, Vite počas vývoja servíruje váš kód priamo do prehliadača, čo znamená okamžitý štart servera bez ohľadu na veľkosť vášho projektu a bleskurýchle aktualizácie.

Spustenie vývojového servera

Spustite vývojový server:

npm run dev

Uvidíte:

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

Tento terminál nechajte otvorený počas vývoja.

Nette Vite plugin automaticky detekuje, keď:

1. Vite dev server beží
2. Vaša Nette aplikácia je v režime ladenia

Keď sú splnené obe podmienky, Nette Assets načíta súbory z Vite dev servera namiesto kompilovaného adresára:

{asset 'app.js'}
{* Vo vývoji: <script src="http://localhost:5173/app.js" type="module"></script> *}
{* V produkcii: <script src="/assets/app-4a8f9c7.js" type="module"></script> *}

Nie je potrebná žiadna konfigurácia – jednoducho to funguje!

Práca na rôznych doménach

Ak váš vývojový server beží na niečom inom ako localhost (napríklad myapp.local), môžete naraziť na problémy s CORS (Cross-Origin Resource Sharing). CORS je bezpečnostná funkcia vo webových prehliadačoch, ktorá predvolene blokuje požiadavky medzi rôznymi doménami. Keď vaša PHP aplikácia beží na myapp.local, ale Vite beží na localhost:5173, prehliadač ich považuje za rôzne domény a blokuje požiadavky.

Máte dve možnosti, ako to vyriešiť:

Možnosť 1: Konfigurácia CORS

Najjednoduchším riešením je povoliť cross-origin požiadavky z vašej PHP aplikácie:

export default defineConfig({
	// ... iná konfigurácia ...

	server: {
		cors: {
			origin: 'http://myapp.local',  // URL vašej PHP aplikácie
		},
	},
});

Možnosť 2: Spustite Vite na vašej doméne

Ďalším riešením je spustiť Vite na rovnakej doméne ako vaša PHP aplikácia.

export default defineConfig({
	// ... iná konfigurácia ...

	server: {
		host: 'myapp.local',  // rovnaké ako vaša PHP aplikácia
	},
});

V skutočnosti aj v tomto prípade musíte nakonfigurovať CORS, pretože dev server beží na rovnakom hostname, ale na inom porte. V tomto prípade však CORS automaticky konfiguruje Nette Vite plugin.

Vývoj s HTTPS

Ak vyvíjate na HTTPS, potrebujete certifikáty pre váš Vite vývojový server. Najjednoduchší spôsob je použiť plugin, ktorý automaticky generuje certifikáty:

npm install -D vite-plugin-mkcert

Tu je návod, ako ho nakonfigurovať v vite.config.ts:

import mkcert from 'vite-plugin-mkcert';

export default defineConfig({
	// ... iná konfigurácia ...

	plugins: [
		mkcert(),  // automaticky generuje certifikáty a povolí https
		nette(),
	],
});

Upozorňujeme, že ak používate konfiguráciu CORS (možnosť 1 z vyššie uvedených), musíte aktualizovať URL pôvodu, aby používala https:// namiesto http://.

Produkčné buildy

Vytvorte optimalizované produkčné súbory:

npm run build

Vite bude:

• Minifikovať všetok JavaScript a CSS
• Rozdeliť kód na optimálne časti
• Generovať hashované názvy súborov pre cache-busting
• Vytvoriť manifest súbor pre Nette Assets

Príklad výstupu:

www/assets/
├── app-4f3a2b1c.js       # Váš hlavný JavaScript (minifikovaný)
├── app-7d8e9f2a.css      # Extrahovaný CSS (minifikovaný)
├── vendor-8c4b5e6d.js    # Zdieľané závislosti
└── .vite/
	└── manifest.json     # Mapovanie pre Nette Assets

Hashované názvy súborov zaisťujú, že prehliadače vždy načítajú najnovšiu verziu.

Verejný priečinok

Súbory v adresári assets/public/ sú kopírované do výstupu bez spracovania:

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

Odkazujte na ne normálne:

{* Tieto súbory sú kopírované tak, ako sú *}
<link rel="icon" href={asset 'favicon.ico'}>
<meta property="og:image" content={asset 'images/og-image.jpg'}>

Pre verejné súbory môžete použiť funkcie FilesystemMapper:

assets:
	mapping:
		default:
			type: vite
			path: assets
			extension: [webp, jpg, png]  # Skúste najprv WebP
			versioning: true             # Pridajte cache-busting

V konfigurácii vite.config.ts môžete zmeniť verejný priečinok pomocou možnosti publicDir.

Dynamické importy

Vite automaticky rozdeľuje kód pre optimálne načítanie. Dynamické importy vám umožňujú načítať kód iba vtedy, keď je skutočne potrebný, čím sa znižuje počiatočná veľkosť balíka:

// Načítajte ťažké komponenty na požiadanie
button.addEventListener('click', async () => {
	let { Chart } = await import('./components/chart.js')
	new Chart(data)
})

Dynamické importy vytvárajú samostatné časti, ktoré sa načítavajú iba vtedy, keď sú potrebné. Toto sa nazýva „code splitting“ a je to jedna z najvýkonnejších funkcií Vite. Keď použijete dynamické importy, Vite automaticky vytvorí samostatné JavaScript súbory pre každý dynamicky importovaný modul.

Tag {asset 'app.js'} automaticky neprednačítava tieto dynamické časti. Toto je zámerné správanie – nechceme sťahovať kód, ktorý sa možno nikdy nepoužije. Časti sa sťahujú iba vtedy, keď sa vykoná dynamický import.

Ak však viete, že určité dynamické importy sú kritické a budú čoskoro potrebné, môžete ich prednačítať:

{* Hlavný vstupný bod *}
{asset 'app.js'}

{* Prednačítajte kritické dynamické importy *}
{preload 'components/chart.js'}

Týmto sa prehliadaču povie, aby stiahol komponent grafu na pozadí, takže je okamžite pripravený, keď je potrebný.

Podpora TypeScriptu

TypeScript funguje hneď po vybalení:

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

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

Odkazujte na TypeScript súbory normálne:

{asset 'main.ts'}

Pre plnú podporu TypeScriptu ho nainštalujte:

npm install -D typescript

Dodatočná konfigurácia Vite

Tu sú niektoré užitočné možnosti konfigurácie Vite s podrobnými vysvetleniami:

export default defineConfig({
	// Koreňový adresár obsahujúci zdrojové assets
	root: 'assets',

	// Priečinok, ktorého obsah sa kopíruje do výstupného adresára tak, ako je
	// Predvolené: 'public' (relatívne k 'root')
	publicDir: 'public',

	build: {
		// Kam umiestniť skompilované súbory (relatívne k 'root')
		outDir: '../www/assets',

		// Vyprázdniť výstupný adresár pred buildom?
		// Užitočné na odstránenie starých súborov z predchádzajúcich buildov
		emptyOutDir: true,

		// Podadresár v rámci outDir pre generované časti a assets
		// To pomáha organizovať výstupnú štruktúru
		assetsDir: 'static',

		rollupOptions: {
			// Vstupný(é) bod(y) - môže byť jeden súbor alebo pole súborov
			// Každý vstupný bod sa stáva samostatným balíkom
			input: [
				'app.js',      // hlavná aplikácia
				'admin.js',    // administrátorský panel
			],
		},
	},

	server: {
		// Hostiteľ, na ktorý sa má naviazať dev server
		// Použite '0.0.0.0' na vystavenie do siete
		host: 'localhost',

		// Port pre dev server
		port: 5173,

		// Konfigurácia CORS pre cross-origin požiadavky
		cors: {
			origin: 'http://myapp.local',
		},
	},

	css: {
		// Povoliť CSS source mapy vo vývoji
		devSourcemap: true,
	},

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

To je všetko! Teraz máte moderný build systém integrovaný s Nette Assets.