Vite Integráció

A Nette Assets zökkenőmentesen integrálódik a Vite-tel, így az összes előnyét élvezheti, miközben a sablonokat a szokásos módon írja.

Vite beállítása

Állítsuk be a Vite-et lépésről lépésre. Ne aggódj, ha még új vagy a build eszközök terén – mindent elmagyarázunk!

1. lépés: Vite telepítése

Először telepítsd a Vite-et és a Nette plugint a projektedbe:

npm install -D vite @nette/vite-plugin

Ez telepíti a Vite-et és egy speciális plugint, amely segít a Vite-nek tökéletesen működni a Nette-tel.

2. lépés: Projektstruktúra

A standard megközelítés az, hogy a forrás asset fájlokat a projekt gyökerében lévő assets/ mappába helyezzük, a fordított verziókat pedig a www/assets/ mappába:

web-project/
├── assets/                   ← forrásfájlok (SCSS, TypeScript, forrásképek)
│   ├── public/               ← statikus fájlok (változatlanul másolva)
│   │   └── favicon.ico
│   ├── images/
│   │   └── logo.png
│   ├── app.js                ← fő belépési pont
│   └── style.css             ← a stíluslapjaid
└── www/                      ← nyilvános könyvtár (dokumentum gyökér)
	├── assets/               ← ide kerülnek a fordított fájlok
	└── index.php

Az assets/ mappa tartalmazza a forrásfájljaidat – a kódot, amit írsz. A Vite feldolgozza ezeket a fájlokat, és a fordított verziókat a www/assets/ mappába helyezi.

3. lépés: Vite konfigurálása

Hozzon létre egy vite.config.ts fájlt a projekt gyökerében. Ez a fájl megmondja a Vite-nek, hol találja a forrásfájlokat és hova tegye a fordított fájlokat.

A Nette Vite plugin intelligens alapértelmezett beállításokkal érkezik, amelyek leegyszerűsítik a konfigurációt. Feltételezi, hogy a frontend forrásfájlok az assets/ könyvtárban vannak (root opció), és a fordított fájlok a www/assets/ mappába kerülnek (outDir opció). Csak a belépési pontot kell megadnia:

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

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

Ha másik könyvtárnevet szeretne megadni az assetek buildeléséhez, néhány opciót módosítania kell:

export default defineConfig({
	root: 'assets', // forrás assetek gyökérkönyvtára

	build: {
		outDir: '../www/assets',  // ahova a fordított fájlok kerülnek
	},

	// ... egyéb konfiguráció ...
});

Az outDir útvonal a root-hoz képest relatív, ezért van ../ az elején.

4. lépés: Nette konfigurálása

Mondja meg a Nette Assets-nek a Vite-ről a common.neon fájlban:

assets:
	mapping:
		default:
			type: vite      # megmondja a Nette-nek, hogy a ViteMapper-t használja
			path: assets

5. lépés: Szkriptek hozzáadása

Add hozzá ezeket a szkripteket a package.json fájlhoz:

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

Most már tudsz:

• npm run dev – fejlesztői szerver indítása hot reloading-gal
• npm run build – optimalizált éles fájlok létrehozása

Belépési pontok

A belépési pont az a fő fájl, ahol az alkalmazásod elindul. Ebből a fájlból importálsz más fájlokat (CSS, JavaScript modulok, képek), létrehozva egy függőségi fát. A Vite követi ezeket az importokat és mindent egybe csomagol.

Példa belépési pont assets/app.js:

// Stílusok importálása
import './style.css'

// JavaScript modulok importálása
import netteForms from 'nette-forms';
import naja from 'naja';

// Alkalmazás inicializálása
netteForms.initOnLoad();
naja.initialize();

A sablonban a belépési pontot a következőképpen illesztheti be:

{asset 'app.js'}

A Nette Assets automatikusan generálja az összes szükséges HTML taget – JavaScript, CSS és bármely más függőség.

Több belépési pont

Nagyobb alkalmazásoknak gyakran külön belépési pontokra van szükségük:

export default defineConfig({
	plugins: [
		nette({
			entry: [
				'app.js',      // nyilvános oldalak
				'admin.js',    // admin panel
			],
		}),
	],
});

Használd őket különböző sablonokban:

{* Nyilvános oldalakon *}
{asset 'app.js'}

{* Admin panelen *}
{asset 'admin.js'}

Fontos: Forrás vs. fordított fájlok

Fontos megérteni, hogy éles környezetben csak a következőket töltheti be:

1. A entry fájlban definiált belépési pontok
2. Fájlok az assets/public/ könyvtárból

Nem tölthet be {asset} segítségével tetszőleges fájlokat az assets/ könyvtárból – csak azokat az asseteket, amelyekre JavaScript vagy CSS fájlok hivatkoznak. Ha a fájlra sehol sem hivatkoznak, az nem lesz fordítva. Ha más asseteket is tudatosítani szeretne a Vite-tel, áthelyezheti őket a public mappa-be.

Kérjük, vegye figyelembe, hogy alapértelmezés szerint a Vite az összes 4KB-nál kisebb assetet beágyazza, így ezekre a fájlokra nem hivatkozhat közvetlenül. (Lásd Vite dokumentáció).

{* ✓ Ez működik - ez egy belépési pont *}
{asset 'app.js'}

{* ✓ Ez működik - az assets/public/ mappában van *}
{asset 'favicon.ico'}

{* ✗ Ez nem fog működni - véletlenszerű fájl az assets/ mappában *}
{asset 'components/button.js'}

Fejlesztői mód

A fejlesztői mód teljesen opcionális, de jelentős előnyökkel jár, ha engedélyezve van. A fő előny a Hot Module Replacement (HMR) – azonnal láthatja a változásokat az alkalmazás állapotának elvesztése nélkül, ami sokkal simábbá és gyorsabbá teszi a fejlesztési élményt.

A Vite egy modern build eszköz, amely hihetetlenül gyorssá teszi a fejlesztést. A hagyományos bundlerekkel ellentétben a Vite közvetlenül a böngészőnek szolgálja ki a kódot fejlesztés közben, ami azt jelenti, hogy azonnali szerverindítás történik, függetlenül a projekt méretétől, és villámgyors frissítések.

Fejlesztői szerver indítása

Futtassa a fejlesztői szervert:

npm run dev

Látni fogja:

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

Tartsa nyitva ezt a terminált a fejlesztés során.

A Nette Vite plugin automatikusan felismeri, ha:

1. A Vite dev szerver fut
2. A Nette alkalmazás debug módban van

Ha mindkét feltétel teljesül, a Nette Assets a Vite dev szerverről tölti be a fájlokat a fordított könyvtár helyett:

{asset 'app.js'}
{* Fejlesztésben: <script src="http://localhost:5173/app.js" type="module"></script> *}
{* Éles környezetben: <script src="/assets/app-4a8f9c7.js" type="module"></script> *}

Nincs szükség konfigurációra – egyszerűen működik!

Különböző domaineken való munka

Ha a fejlesztői szervered nem localhost-on (például myapp.local-on) fut, akkor CORS (Cross-Origin Resource Sharing) problémákkal találkozhatsz. A CORS egy biztonsági funkció a webböngészőkben, amely alapértelmezés szerint blokkolja a különböző domainek közötti kéréseket. Amikor a PHP alkalmazásod myapp.local-on fut, de a Vite localhost:5173-on, a böngésző ezeket különböző domaineknek tekinti, és blokkolja a kéréseket.

Két lehetőséged van ennek megoldására:

1. opció: CORS konfigurálása

A legegyszerűbb megoldás, ha engedélyezi a cross-origin kéréseket a PHP alkalmazásából:

export default defineConfig({
	// ... egyéb konfiguráció ...

	server: {
		cors: {
			origin: 'http://myapp.local',  // a PHP alkalmazásod URL-je
		},
	},
});

2. opció: Futtassa a Vite-et a domainjén

A másik megoldás, ha a Vite-et ugyanazon a domainen futtatja, mint a PHP alkalmazását.

export default defineConfig({
	// ... egyéb konfiguráció ...

	server: {
		host: 'myapp.local',  // ugyanaz, mint a PHP alkalmazásod
	},
});

Valójában ebben az esetben is konfigurálnia kell a CORS-t, mert a dev szerver ugyanazon a hostnéven, de más porton fut. Azonban ebben az esetben a CORS-t a Nette Vite plugin automatikusan konfigurálja.

HTTPS fejlesztés

Ha HTTPS-en fejlesztesz, tanúsítványokra lesz szükséged a Vite fejlesztői szerveredhez. A legegyszerűbb módja egy olyan plugin használata, amely automatikusan generál tanúsítványokat:

npm install -D vite-plugin-mkcert

Így konfigurálhatja a vite.config.ts fájlban:

import mkcert from 'vite-plugin-mkcert';

export default defineConfig({
	// ... egyéb konfiguráció ...

	plugins: [
		mkcert(),  // automatikusan generál tanúsítványokat és engedélyezi a https-t
		nette(),
	],
});

Ne feledje, hogy ha a CORS konfigurációt használja (az 1. opciót fentebb), akkor frissítenie kell az origin URL-t https:// használatára http:// helyett.

Éles build-ek

Hozzon létre optimalizált éles fájlokat:

npm run build

A Vite:

• Minifikálja az összes JavaScriptet és CSS-t
• Optimális részekre osztja a kódot
• Hash-elt fájlneveket generál a gyorsítótár törléséhez
• Létrehoz egy manifest fájlt a Nette Assets számára

Példa kimenet:

www/assets/
├── app-4f3a2b1c.js       # A fő JavaScripted (minifikált)
├── app-7d8e9f2a.css      # Kinyert CSS (minifikált)
├── vendor-8c4b5e6d.js    # Megosztott függőségek
└── .vite/
	└── manifest.json     # Leképezés a Nette Assets számára

A hash-elt fájlnevek biztosítják, hogy a böngészők mindig a legújabb verziót töltsék be.

Nyilvános mappa

Az assets/public/ könyvtárban lévő fájlok feldolgozás nélkül másolódnak a kimenetbe:

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

Hivatkozzon rájuk normálisan:

{* Ezek a fájlok változatlanul másolódnak *}
<link rel="icon" href={asset 'favicon.ico'}>
<meta property="og:image" content={asset 'images/og-image.jpg'}>

Nyilvános fájlokhoz használhatja a FilesystemMapper funkcióit:

assets:
	mapping:
		default:
			type: vite
			path: assets
			extension: [webp, jpg, png]  # Először a WebP-t próbálja
			versioning: true             # Gyorsítótár törlés hozzáadása

A vite.config.ts konfigurációban a publicDir opcióval módosíthatja a nyilvános mappát.

Dinamikus importok

A Vite automatikusan felosztja a kódot az optimális betöltés érdekében. A dinamikus importok lehetővé teszik, hogy a kódot csak akkor töltse be, amikor arra ténylegesen szükség van, csökkentve az kezdeti csomagméretet:

// Nehéz komponensek betöltése igény szerint
button.addEventListener('click', async () => {
	let { Chart } = await import('./components/chart.js')
	new Chart(data)
})

A dinamikus importok külön chunkokat hoznak létre, amelyek csak akkor töltődnek be, amikor ténylegesen szükség van rájuk. Ezt “kód felosztásnak” nevezik, és ez a Vite egyik legerősebb funkciója. Amikor dinamikus importokat használ, a Vite automatikusan külön JavaScript fájlokat hoz létre minden dinamikusan importált modulhoz.

Az {asset 'app.js'} tag nem tölti be automatikusan ezeket a dinamikus chunkokat. Ez szándékos viselkedés – nem akarunk olyan kódot letölteni, amelyet esetleg soha nem használnak. A chunkok csak akkor töltődnek le, amikor a dinamikus import végrehajtásra kerül.

Azonban, ha tudja, hogy bizonyos dinamikus importok kritikusak, és hamarosan szükség lesz rájuk, előtöltheti őket:

{* Fő belépési pont *}
{asset 'app.js'}

{* Kritikus dinamikus importok előtöltése *}
{preload 'components/chart.js'}

Ez azt mondja a böngészőnek, hogy töltse le a diagramkomponenst a háttérben, így azonnal készen áll, amikor szükség van rá.

TypeScript támogatás

A TypeScript azonnal működik:

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

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

Hivatkozzon a TypeScript fájlokra normálisan:

{asset 'main.ts'}

A teljes TypeScript támogatáshoz telepítse:

npm install -D typescript

További Vite konfiguráció

Íme néhány hasznos Vite konfigurációs opció részletes magyarázattal:

export default defineConfig({
	// A forrás asseteket tartalmazó gyökérkönyvtár
	root: 'assets',

	// Az a mappa, amelynek tartalma változatlanul másolódik a kimeneti könyvtárba
	// Alapértelmezett: 'public' (a 'root'-hoz képest relatív)
	publicDir: 'public',

	build: {
		// Hova kerüljenek a fordított fájlok (a 'root'-hoz képest relatív)
		outDir: '../www/assets',

		// Ürítse ki a kimeneti könyvtárat a buildelés előtt?
		// Hasznos a régi fájlok eltávolításához az előző buildekből
		emptyOutDir: true,

		// Alkönvtár az outDir-en belül a generált chunkok és assetek számára
		// Ez segít a kimeneti struktúra rendezésében
		assetsDir: 'static',

		rollupOptions: {
			// Belépési pont(ok) - lehet egyetlen fájl vagy fájltömb
			// Minden belépési pont külön csomaggá válik
			input: [
				'app.js',      // fő alkalmazás
				'admin.js',    // admin panel
			],
		},
	},

	server: {
		// Host, amelyhez a dev szerver kötődik
		// Használja a '0.0.0.0'-t a hálózaton való közzétételhez
		host: 'localhost',

		// Port a dev szerverhez
		port: 5173,

		// CORS konfiguráció a cross-origin kérésekhez
		cors: {
			origin: 'http://myapp.local',
		},
	},

	css: {
		// CSS forrástérképek engedélyezése fejlesztésben
		devSourcemap: true,
	},

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

Ennyi! Most már van egy modern build rendszered, amely integrálva van a Nette Assets-szel.