Intégration de Vite

Nette Assets s'intègre parfaitement à Vite, vous bénéficiez donc de tous ces avantages tout en écrivant vos templates comme d'habitude.

Configuration de Vite

Configurons Vite étape par étape. Ne vous inquiétez pas si vous débutez avec les outils de build – nous allons tout vous expliquer !

Étape 1 : Installer Vite

Tout d'abord, installez Vite et le plugin Nette dans votre projet :

npm install -D vite @nette/vite-plugin

Ceci installe Vite et un plugin spécial qui aide Vite à fonctionner parfaitement avec Nette.

Étape 2 : Structure du projet

L'approche standard consiste à placer les fichiers d'assets source dans un dossier assets/ à la racine de votre projet, et les versions compilées dans www/assets/ :

web-project/
├── assets/                   ← fichiers source (SCSS, TypeScript, images source)
│   ├── public/               ← fichiers statiques (copiés tels quels)
│   │   └── favicon.ico
│   ├── images/
│   │   └── logo.png
│   ├── app.js                ← point d'entrée principal
│   └── style.css             ← vos styles
└── www/                      ← répertoire public (racine du document)
	├── assets/               ← les fichiers compilés iront ici
	└── index.php

Le dossier assets/ contient vos fichiers source – le code que vous écrivez. Vite traitera ces fichiers et placera les versions compilées dans www/assets/.

Étape 3 : Configurer Vite

Créez un fichier vite.config.ts à la racine de votre projet. Ce fichier indique à Vite où trouver vos fichiers source et où placer les fichiers compilés.

Le plugin Nette Vite est livré avec des valeurs par défaut intelligentes qui simplifient la configuration. Il suppose que vos fichiers source front-end se trouvent dans le répertoire assets/ (option root) et que les fichiers compilés vont dans www/assets/ (option outDir). Vous n'avez qu'à spécifier le point d'entrée :

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

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

Si vous souhaitez spécifier un autre nom de répertoire pour construire vos assets, vous devrez modifier quelques options :

export default defineConfig({
	root: 'assets', // répertoire racine des assets source

	build: {
		outDir: '../www/assets',  // où vont les fichiers compilés
	},

	// ... autre configuration ...
});

Le chemin outDir est considéré comme relatif à root, c'est pourquoi il y a ../ au début.

Étape 4 : Configurer Nette

Indiquez à Nette Assets l'intégration de Vite dans votre common.neon :

assets:
	mapping:
		default:
			type: vite      # indique à Nette d'utiliser le ViteMapper
			path: assets

Étape 5 : Ajouter des scripts

Ajoutez ces scripts à votre package.json :

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

Maintenant, vous pouvez :

• npm run dev – démarrer le serveur de développement avec rechargement à chaud
• npm run build – créer des fichiers de production optimisés

Points d'entrée

Un point d'entrée est le fichier principal où votre application démarre. À partir de ce fichier, vous importez d'autres fichiers (CSS, modules JavaScript, images), créant ainsi un arbre de dépendances. Vite suit ces importations et regroupe tout.

Exemple de point d'entrée assets/app.js :

// Importe les styles
import './style.css'

// Importe les modules JavaScript
import netteForms from 'nette-forms';
import naja from 'naja';

// Initialise votre application
netteForms.initOnLoad();
naja.initialize();

Dans le template, vous pouvez insérer un point d'entrée comme suit :

{asset 'app.js'}

Nette Assets génère automatiquement toutes les balises HTML nécessaires – JavaScript, CSS et toutes les autres dépendances.

Points d'entrée multiples

Les applications plus grandes ont souvent besoin de points d'entrée séparés :

export default defineConfig({
	plugins: [
		nette({
			entry: [
				'app.js',      // pages publiques
				'admin.js',    // panneau d'administration
			],
		}),
	],
});

Utilisez-les dans différents templates :

{* Dans les pages publiques *}
{asset 'app.js'}

{* Dans le panneau d'administration *}
{asset 'admin.js'}

Important : Fichiers source vs compilés

Il est crucial de comprendre qu'en production, vous ne pouvez charger que :

1. Les points d'entrée définis dans entry
2. Les fichiers du répertoire assets/public/

Vous ne pouvez pas charger en utilisant {asset} des fichiers arbitraires depuis assets/ – seulement les assets référencés par des fichiers JavaScript ou CSS. Si votre fichier n'est référencé nulle part, il ne sera pas compilé. Si vous voulez que Vite soit conscient d'autres assets, vous pouvez les déplacer vers le dossier public.

Veuillez noter que par défaut, Vite intégrera tous les assets de moins de 4 Ko, vous ne pourrez donc pas référencer ces fichiers directement. (Voir la documentation Vite).

{* ✓ Cela fonctionne - c'est un point d'entrée *}
{asset 'app.js'}

{* ✓ Cela fonctionne - c'est dans assets/public/ *}
{asset 'favicon.ico'}

{* ✗ Cela ne fonctionnera pas - fichier aléatoire dans assets/ *}
{asset 'components/button.js'}

Mode développement

Le mode développement est entièrement optionnel mais offre des avantages significatifs lorsqu'il est activé. Le principal avantage est le Hot Module Replacement (HMR) – voyez les changements instantanément sans perdre l'état de l'application, rendant l'expérience de développement beaucoup plus fluide et rapide.

Vite est un outil de build moderne qui rend le développement incroyablement rapide. Contrairement aux bundlers traditionnels, Vite sert votre code directement au navigateur pendant le développement, ce qui signifie un démarrage instantané du serveur quelle que soit la taille de votre projet et des mises à jour ultra-rapides.

Démarrage du serveur de développement

Lancez le serveur de développement :

npm run dev

Vous verrez :

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

Gardez ce terminal ouvert pendant le développement.

Le plugin Nette Vite détecte automatiquement quand :

1. Le serveur de développement Vite est en cours d'exécution
2. Votre application Nette est en mode débogage

Lorsque ces deux conditions sont remplies, Nette Assets charge les fichiers depuis le serveur de développement Vite au lieu du répertoire compilé :

{asset 'app.js'}
{* En développement : <script src="http://localhost:5173/app.js" type="module"></script> *}
{* En production : <script src="/assets/app-4a8f9c7.js" type="module"></script> *}

Aucune configuration nécessaire – ça marche tout seul !

Travailler sur différents domaines

Si votre serveur de développement s'exécute sur autre chose que localhost (comme myapp.local), vous pourriez rencontrer des problèmes de CORS (Cross-Origin Resource Sharing). CORS est une fonctionnalité de sécurité des navigateurs web qui bloque par défaut les requêtes entre différents domaines. Lorsque votre application PHP s'exécute sur myapp.local mais que Vite s'exécute sur localhost:5173, le navigateur les considère comme des domaines différents et bloque les requêtes.

Vous avez deux options pour résoudre ce problème :

Option 1 : Configurer CORS

La solution la plus simple est d'autoriser les requêtes cross-origin depuis votre application PHP :

export default defineConfig({
	// ... autre configuration ...

	server: {
		cors: {
			origin: 'http://myapp.local',  // l'URL de votre application PHP
		},
	},
});

Option 2 : Exécuter Vite sur votre domaine

L'autre solution est de faire en sorte que Vite s'exécute sur le même domaine que votre application PHP.

export default defineConfig({
	// ... autre configuration ...

	server: {
		host: 'myapp.local',  // le même que votre application PHP
	},
});

En fait, même dans ce cas, vous devez configurer CORS car le serveur de développement s'exécute sur le même nom d'hôte mais sur un port différent. Cependant, dans ce cas, CORS est automatiquement configuré par le plugin Nette Vite.

Développement HTTPS

Si vous développez en HTTPS, vous avez besoin de certificats pour votre serveur de développement Vite. Le moyen le plus simple est d'utiliser un plugin qui génère automatiquement des certificats :

npm install -D vite-plugin-mkcert

Voici comment le configurer dans vite.config.ts :

import mkcert from 'vite-plugin-mkcert';

export default defineConfig({
	// ... autre configuration ...

	plugins: [
		mkcert(),  // génère automatiquement des certificats et active https
		nette(),
	],
});

Notez que si vous utilisez la configuration CORS (Option 1 ci-dessus), vous devez mettre à jour l'URL d'origine pour utiliser https:// au lieu de http://.

Builds de production

Créez des fichiers de production optimisés :

npm run build

Vite va :

• Minifier tout le JavaScript et le CSS
• Diviser le code en morceaux optimaux
• Générer des noms de fichiers hachés pour le cache-busting
• Créer un fichier manifest pour Nette Assets

Exemple de sortie :

www/assets/
├── app-4f3a2b1c.js       # Votre JavaScript principal (minifié)
├── app-7d8e9f2a.css      # CSS extrait (minifié)
├── vendor-8c4b5e6d.js    # Dépendances partagées
└── .vite/
	└── manifest.json     # Mappage pour Nette Assets

Les noms de fichiers hachés garantissent que les navigateurs chargent toujours la dernière version.

Dossier public

Les fichiers du répertoire assets/public/ sont copiés dans la sortie sans traitement :

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

Référencez-les normalement :

{* Ces fichiers sont copiés tels quels *}
<link rel="icon" href={asset 'favicon.ico'}>
<meta property="og:image" content={asset 'images/og-image.jpg'}>

Pour les fichiers publics, vous pouvez utiliser les fonctionnalités de FilesystemMapper :

assets:
	mapping:
		default:
			type: vite
			path: assets
			extension: [webp, jpg, png]  # Essayer WebP en premier
			versioning: true             # Ajouter le cache-busting

Dans la configuration vite.config.ts, vous pouvez modifier le dossier public en utilisant l'option publicDir.

Imports dynamiques

Vite divise automatiquement le code pour un chargement optimal. Les imports dynamiques vous permettent de charger du code uniquement lorsqu'il est réellement nécessaire, réduisant ainsi la taille initiale du bundle :

// Charge les composants lourds à la demande
button.addEventListener('click', async () => {
	let { Chart } = await import('./components/chart.js')
	new Chart(data)
})

Les imports dynamiques créent des chunks séparés qui ne sont chargés que lorsque nécessaire. C'est ce qu'on appelle le “code splitting” et c'est l'une des fonctionnalités les plus puissantes de Vite. Lorsque vous utilisez des imports dynamiques, Vite crée automatiquement des fichiers JavaScript séparés pour chaque module importé dynamiquement.

La balise {asset 'app.js'} ne précharge pas automatiquement ces chunks dynamiques. C'est un comportement intentionnel – nous ne voulons pas télécharger du code qui pourrait ne jamais être utilisé. Les chunks ne sont téléchargés que lorsque l'import dynamique est exécuté.

Cependant, si vous savez que certains imports dynamiques sont critiques et seront nécessaires bientôt, vous pouvez les précharger :

{* Point d'entrée principal *}
{asset 'app.js'}

{* Précharge les imports dynamiques critiques *}
{preload 'components/chart.js'}

Cela indique au navigateur de télécharger le composant de graphique en arrière-plan, afin qu'il soit prêt immédiatement lorsque nécessaire.

Support TypeScript

TypeScript fonctionne dès la première utilisation :

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

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

Référencez les fichiers TypeScript normalement :

{asset 'main.ts'}

Pour un support TypeScript complet, installez-le :

npm install -D typescript

Configuration Vite additionnelle

Voici quelques options de configuration Vite utiles avec des explications détaillées :

export default defineConfig({
	// Répertoire racine contenant les assets source
	root: 'assets',

	// Dossier dont le contenu est copié dans le répertoire de sortie tel quel
	// Par défaut : 'public' (relatif à 'root')
	publicDir: 'public',

	build: {
		// Où placer les fichiers compilés (relatif à 'root')
		outDir: '../www/assets',

		// Vider le répertoire de sortie avant la construction ?
		// Utile pour supprimer les anciens fichiers des builds précédentes
		emptyOutDir: true,

		// Sous-répertoire dans outDir pour les chunks et assets générés
		// Cela aide à organiser la structure de sortie
		assetsDir: 'static',

		rollupOptions: {
			// Point(s) d'entrée - peut être un seul fichier ou un tableau de fichiers
			// Chaque point d'entrée devient un bundle séparé
			input: [
				'app.js',      // application principale
				'admin.js',    // panneau d'administration
			],
		},
	},

	server: {
		// Hôte sur lequel lier le serveur de développement
		// Utilisez '0.0.0.0' pour exposer au réseau
		host: 'localhost',

		// Port pour le serveur de développement
		port: 5173,

		// Configuration CORS pour les requêtes cross-origin
		cors: {
			origin: 'http://myapp.local',
		},
	},

	css: {
		// Activer les source maps CSS en développement
		devSourcemap: true,
	},

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

C'est tout ! Vous avez maintenant un système de build moderne intégré à Nette Assets.