Integrácia Vite

***************

<div class=perex>

Moderné JavaScript aplikácie vyžadujú sofistikované build nástroje. Nette Assets poskytuje prvotriednu integráciu s [Vite |https://vitejs.dev/], nástrojom na tvorbu frontendu novej generácie. Získajte bleskurýchly vývoj s Hot Module Replacement (HMR) a optimalizované produkčné buildy bez problémov s konfiguráciou.

- **Nulová konfigurácia** – automatický most medzi Vite a PHP šablónami

- **Kompletná správa závislostí** – jeden tag spracuje všetky assets

- **Hot Module Replacement** – okamžité aktualizácie JavaScriptu a CSS

- **Optimalizované produkčné buildy** – code splitting a tree shaking

</div>

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:

```shell

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/`:

/--pre

<b>web-project/</b>

├── <b>assets/</b> ← zdrojové súbory (SCSS, TypeScript, zdrojové obrázky)

│ ├── <b>public/</b> ← statické súbory (kopírované tak, ako sú)

│ │ └── <b>favicon.ico</b>

│ ├── <b>images/</b>

│ │ └── <b>logo.png</b>

│ ├── <b>app.js</b> ← hlavný vstupný bod

│ └── <b>style.css</b> ← vaše štýly

└── <b>www/</b> ← verejný adresár (document root)

├── <b>assets/</b> ← sem pôjdu kompilované súbory

└── <b>index.php</b>

\--

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|#Entry Points]:

```js

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í:

```js

export default defineConfig({

root: 'assets', // koreňový adresár zdrojových assetov

build: {

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

},

// ... iná konfigurácia ...

});

```

.[note]

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`:

```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`:

```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`:

```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:

```latte

{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:

```js

export default defineConfig({

plugins: [

nette({

entry: [

'app.js', // verejné stránky

'admin.js', // administrátorský panel

],

}),

],

});

```

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

```latte

{* 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 |#public folder].

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 |https://vite.dev/guide/assets.html]).

```latte

{* ✓ 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:

```shell

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:

```latte

{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:

```js

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.

```js

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:

```shell

npm install -D vite-plugin-mkcert

```

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

```js

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:

```shell

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:

```latte

{* 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:

```neon

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:

```js

// 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ť:

```latte

{* 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í:

```ts

// 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:

```latte

{asset 'main.ts'}

```

Pre plnú podporu TypeScriptu ho nainštalujte:

```shell

npm install -D typescript

```

Dodatočná konfigurácia Vite

===========================

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

```js

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.