Vite интеграция

Модерните JavaScript приложения изискват сложни инструменти за изграждане. Nette Assets предоставя първокласна интеграция с Vite, инструментът за изграждане на фронтенд от следващо поколение. Получете светкавично бързо развитие с Hot Module Replacement (HMR) и оптимизирани продукционни компилации без никакви проблеми с конфигурацията.

  • Нулева конфигурация – автоматичен мост между Vite и PHP шаблони
  • Пълно управление на зависимостите – един таг обработва всички активи
  • Hot Module Replacement – незабавни JavaScript и CSS актуализации
  • Оптимизирани продукционни компилации – разделяне на кода и tree shaking

Nette Assets се интегрира безпроблемно с Vite, така че получавате всички тези предимства, докато пишете шаблоните си както обикновено.

Настройка на Vite

Нека настроим Vite стъпка по стъпка. Не се притеснявайте, ако сте нов в инструментите за изграждане – ще обясним всичко!

Стъпка 1: Инсталирайте Vite

Първо, инсталирайте Vite и Nette плъгина във вашия проект:

npm install -D vite @nette/vite-plugin

Това инсталира Vite и специален плъгин, който помага на Vite да работи перфектно с Nette.

Стъпка 2: Структура на проекта

Стандартният подход е да поставите изходните файлове на активи в папка assets/ в корена на проекта, а компилираните версии в www/assets/:

web-project/
├── assets/                   ← изходни файлове (SCSS, TypeScript, изходни изображения)
│   ├── public/               ← статични файлове (копират се както са)
│   │   └── favicon.ico
│   ├── images/
│   │   └── logo.png
│   ├── app.js                ← основна входна точка
│   └── style.css             ← вашите стилове
└── www/                      ← публична директория (документен корен)
	├── assets/               ← компилираните файлове ще отидат тук
	└── index.php

Папката assets/ съдържа вашите изходни файлове – кода, който пишете. Vite ще обработи тези файлове и ще постави компилираните версии в www/assets/.

Стъпка 3: Конфигурирайте Vite

Създайте файл vite.config.ts в корена на проекта. Този файл казва на Vite къде да намери вашите изходни файлове и къде да постави компилираните.

Плъгинът Nette Vite идва с интелигентни настройки по подразбиране, които опростяват конфигурацията. Той предполага, че вашите изходни фронтенд файлове са в директорията assets/ (опция root) и компилираните файлове отиват в www/assets/ (опция outDir). Трябва само да укажете Входни точки:

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

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

Ако искате да укажете друго име на директория за изграждане на вашите активи, ще трябва да промените няколко опции:

export default defineConfig({
	root: 'assets', // основна директория на изходни активи

	build: {
		outDir: '../www/assets',  // къде отиват компилираните файлове
	},

	// ... друга конфигурация ...
});

Пътят outDir се счита за относителен спрямо root, поради което има ../ в началото.

Стъпка 4: Конфигурирайте Nette

Кажете на Nette Assets за Vite във вашия common.neon:

assets:
	mapping:
		default:
			type: vite      # казва на Nette да използва ViteMapper
			path: assets

Стъпка 5: Добавете скриптове

Добавете тези скриптове към вашия package.json:

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

Сега можете:

  • npm run dev – стартирайте сървър за разработка с горещо презареждане
  • npm run build – създайте оптимизирани продукционни файлове

Входни точки

Входна точка е основният файл, от който започва вашето приложение. От този файл импортирате други файлове (CSS, JavaScript модули, изображения), създавайки дърво на зависимостите. Vite следва тези импорти и пакетира всичко заедно.

Примерна входна точка assets/app.js:

// Импортиране на стилове
import './style.css'

// Импортиране на JavaScript модули
import netteForms from 'nette-forms';
import naja from 'naja';

// Инициализиране на вашето приложение
netteForms.initOnLoad();
naja.initialize();

В шаблона можете да вмъкнете входна точка, както следва:

{asset 'app.js'}

Nette Assets автоматично генерира всички необходими HTML тагове – JavaScript, CSS и всякакви други зависимости.

Множество входни точки

По-големите приложения често се нуждаят от отделни входни точки:

export default defineConfig({
	plugins: [
		nette({
			entry: [
				'app.js',      // публични страници
				'admin.js',    // административен панел
			],
		}),
	],
});

Използвайте ги в различни шаблони:

{* В публични страници *}
{asset 'app.js'}

{* В административен панел *}
{asset 'admin.js'}

Важно: Изходни срещу компилирани файлове

Ключово е да се разбере, че в продукция можете да зареждате само:

  1. Входни точки, дефинирани в entry
  2. Файлове от директорията assets/public/

Не можете да зареждате с {asset} произволни файлове от assets/ – само активи, реферирани от JavaScript или CSS файлове. Ако вашият файл не е рефериран никъде, той няма да бъде компилиран. Ако искате да направите Vite наясно с други активи, можете да ги преместите в Публична папка.

Моля, имайте предвид, че по подразбиране Vite ще вгради всички активи, по-малки от 4KB, така че няма да можете да реферирате тези файлове директно. (Вижте документацията на Vite).

{* ✓ Това работи - това е входна точка *}
{asset 'app.js'}

{* ✓ Това работи - това е в assets/public/ *}
{asset 'favicon.ico'}

{* ✗ Това няма да работи - произволен файл в assets/ *}
{asset 'components/button.js'}

Режим на разработка

Режимът на разработка е напълно опционален, но предоставя значителни предимства, когато е активиран. Основното предимство е Hot Module Replacement (HMR) – вижте промените незабавно, без да губите състоянието на приложението, което прави процеса на разработка много по-плавен и бърз.

Vite е модерен инструмент за изграждане, който прави разработката невероятно бърза. За разлика от традиционните пакетиращи инструменти, Vite обслужва вашия код директно на браузъра по време на разработка, което означава незабавен старт на сървъра, независимо колко голям е вашият проект, и светкавично бързи актуализации.

Стартиране на сървър за разработка

Стартирайте сървъра за разработка:

npm run dev

Ще видите:

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

Дръжте този терминал отворен, докато разработвате.

Плъгинът Nette Vite автоматично открива кога:

  1. Vite dev сървърът работи
  2. Вашето Nette приложение е в режим на отстраняване на грешки

Когато и двете условия са изпълнени, Nette Assets зарежда файлове от Vite dev сървъра вместо от компилираната директория:

{asset 'app.js'}
{* В разработка: <script src="http://localhost:5173/app.js" type="module"></script> *}
{* В продукция: <script src="/assets/app-4a8f9c7.js" type="module"></script> *}

Не е необходима конфигурация – просто работи!

Работа на различни домейни

Ако вашият сървър за разработка работи на нещо различно от localhost (като myapp.local), може да срещнете проблеми с CORS (Cross-Origin Resource Sharing). CORS е функция за сигурност в уеб браузърите, която по подразбиране блокира заявки между различни домейни. Когато вашето PHP приложение работи на myapp.local, но Vite работи на localhost:5173, браузърът ги вижда като различни домейни и блокира заявките.

Имате две опции за решаване на това:

Опция 1: Конфигурирайте CORS

Най-простото решение е да разрешите заявки от различни източници от вашето PHP приложение:

export default defineConfig({
	// ... друга конфигурация ...

	server: {
		cors: {
			origin: 'http://myapp.local',  // URL на вашето PHP приложение
		},
	},
});

Опция 2: Пуснете Vite на вашия домейн

Другото решение е да накарате Vite да работи на същия домейн като вашето PHP приложение.

export default defineConfig({
	// ... друга конфигурация ...

	server: {
		host: 'myapp.local',  // същото като вашето PHP приложение
	},
});

Всъщност, дори в този случай, трябва да конфигурирате CORS, защото dev сървърът работи на същия хост, но на различен порт. Въпреки това, в този случай CORS се конфигурира автоматично от плъгина Nette Vite.

HTTPS разработка

Ако разработвате на HTTPS, имате нужда от сертификати за вашия Vite сървър за разработка. Най-лесният начин е да използвате плъгин, който генерира сертификати автоматично:

npm install -D vite-plugin-mkcert

Ето как да го конфигурирате във vite.config.ts:

import mkcert from 'vite-plugin-mkcert';

export default defineConfig({
	// ... друга конфигурация ...

	plugins: [
		mkcert(),  // генерира сертификати автоматично и активира https
		nette(),
	],
});

Имайте предвид, че ако използвате CORS конфигурацията (Опция 1 отгоре), трябва да актуализирате URL адреса на източника, за да използва https:// вместо http://.

Продукционни компилации

Създайте оптимизирани продукционни файлове:

npm run build

Vite ще:

  • Минифицира целия JavaScript и CSS
  • Раздели кода на оптимални части
  • Генерира хеширани имена на файлове за кеш-изчистване
  • Създаде манифест файл за Nette Assets

Примерен изход:

www/assets/
├── app-4f3a2b1c.js       # Вашият основен JavaScript (минифициран)
├── app-7d8e9f2a.css      # Извлечен CSS (минифициран)
├── vendor-8c4b5e6d.js    # Споделени зависимости
└── .vite/
	└── manifest.json     # Мапиране за Nette Assets

Хешираните имена на файлове гарантират, че браузърите винаги зареждат най-новата версия.

Публична папка

Файловете в директорията assets/public/ се копират в изхода без обработка:

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

Реферирайте ги нормално:

{* Тези файлове се копират както са *}
<link rel="icon" href={asset 'favicon.ico'}>
<meta property="og:image" content={asset 'images/og-image.jpg'}>

За публични файлове можете да използвате функциите на FilesystemMapper:

assets:
	mapping:
		default:
			type: vite
			path: assets
			extension: [webp, jpg, png]  # Първо опитайте WebP
			versioning: true             # Добавете cache-busting

В конфигурацията vite.config.ts можете да промените публичната папка, като използвате опцията publicDir.

Динамични импорти

Vite автоматично разделя кода за оптимално зареждане. Динамичните импорти ви позволяват да зареждате код само когато е наистина необходим, намалявайки първоначалния размер на пакета:

// Зареждане на тежки компоненти при поискване
button.addEventListener('click', async () => {
	let { Chart } = await import('./components/chart.js')
	new Chart(data)
})

Динамичните импорти създават отделни части, които се зареждат само когато е необходимо. Това се нарича “разделяне на кода” и е една от най-мощните функции на Vite. Когато използвате динамични импорти, Vite автоматично създава отделни JavaScript файлове за всеки динамично импортиран модул.

Тагът {asset 'app.js'} не зарежда автоматично тези динамични части. Това е умишлено поведение – не искаме да изтегляме код, който може никога да не бъде използван. Частите се изтеглят само когато динамичният импорт бъде изпълнен.

Въпреки това, ако знаете, че определени динамични импорти са критични и ще са необходими скоро, можете да ги предварително заредите:

{* Основна входна точка *}
{asset 'app.js'}

{* Предварително зареждане на критични динамични импорти *}
{preload 'components/chart.js'}

Това казва на браузъра да изтегли компонента на диаграмата във фонов режим, така че да е готов веднага, когато е необходим.

Поддръжка на TypeScript

TypeScript работи веднага:

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

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

Реферирайте TypeScript файлове нормално:

{asset 'main.ts'}

За пълна поддръжка на TypeScript, инсталирайте го:

npm install -D typescript

Допълнителна конфигурация на Vite

Ето някои полезни опции за конфигурация на Vite с подробни обяснения:

export default defineConfig({
	// Основна директория, съдържаща изходни активи
	root: 'assets',

	// Папка, чието съдържание се копира в изходната директория както е
	// По подразбиране: 'public' (относително спрямо 'root')
	publicDir: 'public',

	build: {
		// Къде да се поставят компилираните файлове (относително спрямо 'root')
		outDir: '../www/assets',

		// Изчистване на изходната директория преди изграждане?
		// Полезно за премахване на стари файлове от предишни компилации
		emptyOutDir: true,

		// Поддиректория в outDir за генерирани части и активи
		// Това помага да се организира изходната структура
		assetsDir: 'static',

		rollupOptions: {
			// Входна(и) точка(и) - може да бъде един файл или масив от файлове
			// Всяка входна точка става отделен пакет
			input: [
				'app.js',      // основно приложение
				'admin.js',    // административен панел
			],
		},
	},

	server: {
		// Хост, към който да се свърже сървърът за разработка
		// Използвайте '0.0.0.0', за да изложите на мрежата
		host: 'localhost',

		// Порт за сървъра за разработка
		port: 5173,

		// CORS конфигурация за заявки от различни източници
		cors: {
			origin: 'http://myapp.local',
		},
	},

	css: {
		// Активиране на CSS source maps в разработка
		devSourcemap: true,
	},

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

Това е! Вече имате модерна система за изграждане, интегрирана с Nette Assets.

  1. Документация
  2. Nette Assets
  3. Vite интеграция
версия: 1.0