README

Intégration optionnelle de Vite.js et Tailwind CSS v4 pour Astral MVC.

⚡ Démarrage dev < 300ms — ESM natif, aucun bundling à froid
🔥 HMR instantané — CSS et JS mis à jour sans rechargement de page
📦 Build production optimisé — tree-shaking Rollup, fichiers hashés
🎨 Tailwind CSS v4 — plugin officiel Vite, zéro config PostCSS
🔌 Intégration en 4 étapes — un ServiceProvider, une variable $vite

Sommaire

Prérequis
Installation
Utilisation quotidienne
- Développement
- Production
API de ViteAssets
Variables d'environnement
Stubs fournis
Comment ça fonctionne
Ajouter Vue 3 ou React
Structure du projet après installation
Licence

Prérequis

Outil	Version minimale
PHP	8.0+
Astral MVC	1.1+
Node.js	18+
npm	9+

Installation

1. Installer le package via Composer

composer require astral-php/astral-vite

2. Enregistrer le ServiceProvider

Ouvrir config/dependencies.php et ajouter ViteServiceProvider après FrameworkServiceProvider :

// config/dependencies.php

use Core\Providers\FrameworkServiceProvider;
use Core\Providers\DatabaseServiceProvider;
use AstralVite\ViteServiceProvider;          // ← importer
use App\Providers\AppServiceProvider;

return [
    FrameworkServiceProvider::class,
    DatabaseServiceProvider::class,
    ViteServiceProvider::class,              // ← ajouter ici
    AppServiceProvider::class,
];

Pourquoi après FrameworkServiceProvider ? ViteServiceProvider appelle View::share('vite', ...). La classe View est instanciée par FrameworkServiceProvider — elle doit donc être enregistrée en premier.

3. Configurer le front-end

a) Copier les stubs

Le dossier vendor/astral-php/astral-vite/stubs/ contient tous les fichiers prêts à l'emploi. Copiez-les à la racine de votre projet :

# Config Vite + npm
cp vendor/astral-php/astral-vite/stubs/vite.config.js .
cp vendor/astral-php/astral-vite/stubs/package.json   .

# Sources front-end
cp -r vendor/astral-php/astral-vite/stubs/resources .

# Layout PHP (adapter selon votre layout existant)
cp vendor/astral-php/astral-vite/stubs/views/layouts/app.php views/layout/

b) Installer les dépendances npm

npm install

Cela installe : vite, tailwindcss, @tailwindcss/vite.

c) Variables .env (optionnel)

Les valeurs par défaut conviennent pour la plupart des projets. Pour personnaliser, ajouter dans .env :

# Défauts — à modifier seulement si nécessaire
VITE_DEV_SERVER=http://localhost:5173
VITE_BUILD_DIR=/build

4. Utiliser $vite dans le layout

$vite est automatiquement disponible dans toutes les vues (partagé via View::share()). Tu as deux options :

Option 1 — Modifier ton layout existant (`views/layout/main.php`)

Supprimer l'import Tailwind CDN (si présent)
Ajouter l'appel à $vite->tags() dans le <head> :

<!-- views/layout/main.php -->
<head>
    <meta charset="UTF-8">
    <title><?= htmlspecialchars($title ?? 'Mon App') ?></title>

    <?= $vite->tags([
        'resources/js/app.js',
        'resources/css/app.css',
    ]) ?>
</head>

Option 2 — Utiliser le layout stub

Copier stubs/views/layouts/app.php vers views/layout/
Adapter le contenu HTML (nav, footer, etc.)

C'est tout. Le package gère le reste automatiquement selon APP_ENV.

Alternative (Un seul entry point)

Si tu préfères n’avoir qu’un seul entry point :

Dans resources/js/app.js :

import '../css/app.css'

Dans le layout :

<?= $vite->tags('resources/js/app.js') ?>

Utilisation quotidienne

Développement

Lancer deux terminaux en parallèle :

# Terminal 1 — Serveur PHP
php -S localhost:8000 -t public

# Terminal 2 — Serveur Vite (HMR)
npm run dev

Accéder à http://localhost:8000.

PHP génère le HTML et les données
Vite sert les assets JS/CSS avec mise à jour instantanée (HMR)
Toute modification CSS ou JS est répercutée sans rechargement de la page

Production

# Compiler les assets
npm run build

Cela génère dans public/build/ :

public/build/
├── manifest.json          ← carte src → fichier hashé (lu par ViteAssets)
└── assets/
    ├── app-Bz3kT9mQ.js    ← JS minifié + tree-shaké
    └── app-Cx4mPrN8.css   ← CSS Tailwind purgé + minifié

En production (APP_ENV=production), $vite->tags() lit manifest.json et génère automatiquement les balises avec les noms de fichiers hashés.

API de ViteAssets

La variable $vite est disponible dans toutes les vues. Elle peut aussi être injectée dans un contrôleur ou un service via le container.

`$vite->tags(string|array $entries): string`

Génère les balises HTML pour un ou plusieurs entry points. C'est la méthode principale — à utiliser dans le layout.

// Un seul entry point
<?= $vite->tags('resources/js/app.js') ?>

// Plusieurs entry points
<?= $vite->tags([
    'resources/js/app.js',
    'resources/css/app.css',
]) ?>

En développement (APP_ENV=development), génère :

<script type="module" src="http://localhost:5173/@vite/client"></script>
<script type="module" src="http://localhost:5173/resources/js/app.js"></script>

En production, génère :

<link rel="stylesheet" href="/build/assets/app-Cx4mPrN8.css">
<script type="module" src="/build/assets/app-Bz3kT9mQ.js"></script>

`$vite->asset(string $path): string`

Retourne l'URL publique d'un asset statique (image, SVG, font…).

<img src="<?= $vite->asset('resources/images/logo.svg') ?>" alt="Logo">
<link rel="icon" href="<?= $vite->asset('resources/images/favicon.png') ?>">

`$vite->isDev(): bool`

Indique si le mode développement est actif. Utile pour du rendu conditionnel.

<?php if ($vite->isDev()): ?>
    <div class="fixed bottom-2 right-2 bg-indigo-600 text-white text-xs px-2 py-1 rounded">
        ⚡ Vite HMR
    </div>
<?php endif; ?>

Injection dans un contrôleur

use AstralVite\ViteAssets;

final class HomeController extends AbstractController
{
    public function __construct(
        private View       $view,
        private ViteAssets $vite,   // ← injecter depuis le container
    ) {}

    public function index(): Response
    {
        $logoUrl = $this->vite->asset('resources/images/logo.svg');
        return $this->render('home/index', compact('logoUrl'));
    }
}

Enregistrer dans app/Providers/AppServiceProvider.php :

$container->bind(HomeController::class, fn($c) => new HomeController(
    view: $c->make(View::class),
    vite: $c->make(ViteAssets::class),   // ← déjà enregistré par ViteServiceProvider
));

Variables d'environnement

Variable	Défaut	Description
`VITE_DEV_SERVER`	`http://localhost:5173`	URL du serveur Vite en mode développement
`VITE_BUILD_DIR`	`/build`	Chemin public vers le dossier de build (relatif à `public/`)

Ces variables sont optionnelles. Les valeurs par défaut conviennent pour la grande majorité des projets.

Stubs fournis

Le dossier stubs/ contient des fichiers de démarrage prêts à l'emploi :

stubs/
├── vite.config.js                   ← Config Vite calibrée pour Astral MVC
├── package.json                     ← Dépendances npm (vite, tailwindcss)
├── .env.example                     ← Variables Vite à ajouter dans .env
├── resources/
│   ├── js/
│   │   ├── app.js                   ← Entry point JS
│   │   └── components/
│   │       ├── flash.js             ← Auto-dismiss des messages flash Astral
│   │       └── confirm.js           ← Confirmation avant suppression (DELETE)
│   └── css/
│       └── app.css                  ← Entry point CSS avec Tailwind v4
└── views/
    └── layouts/
        └── app.php                  ← Layout PHP complet avec $vite->tags()

`flash.js`

Anime et auto-dismiss les messages flash d'Astral MVC après 4 secondes.

Utilise l'attribut data-flash sur vos éléments de flash :

<!-- views/partials/flash.php -->
<?php if ($session->hasFlash('success')): ?>
    <div data-flash="success"
         class="flex items-center gap-3 p-4 rounded-lg bg-green-50 text-green-800 border border-green-200 mb-4">
        <?= htmlspecialchars($session->getFlash('success')) ?>
        <button data-flash-close class="ml-auto text-green-600 hover:text-green-900">✕</button>
    </div>
<?php endif; ?>

`confirm.js`

Ajoute une demande de confirmation avant la soumission des formulaires de suppression. Compatible avec le verb spoofing DELETE d'Astral MVC :

<form method="POST" action="/users/<?= $user->id ?>/delete"
      data-confirm="Supprimer <?= htmlspecialchars($user->name) ?> ?">
    <input type="hidden" name="_method" value="DELETE">
    <?= $csrf->field() ?>
    <button type="submit" class="text-red-600 hover:underline text-sm">
        Supprimer
    </button>
</form>

Comment ça fonctionne

En développement (`APP_ENV=development`)

Navigateur → http://localhost:8000/
               ↓
          PHP (port 8000)
          génère le HTML :
            <script type="module" src="http://localhost:5173/@vite/client"></script>
            <script type="module" src="http://localhost:5173/resources/js/app.js"></script>
               ↓
          Vite (port 5173)
          sert les modules ES natifs
          WebSocket HMR → mise à jour instantanée

Le navigateur charge les modules JS directement depuis Vite via les ES Modules natifs. Aucun bundling à froid — c'est pour ça que le démarrage est quasi-instantané.

En production (`APP_ENV=production`)

npm run build
  ↓
public/build/manifest.json  ←── ViteAssets lit ce fichier
public/build/assets/app-[hash].js
public/build/assets/app-[hash].css

PHP génère :
  <link rel="stylesheet" href="/build/assets/app-Cx4mP.css">
  <script type="module" src="/build/assets/app-Bz3kT.js"></script>

Le build Rollup effectue le tree-shaking (supprime le code mort), le code splitting (chunks partagés chargés une seule fois) et la minification. Tailwind CSS v4 purge automatiquement les classes non utilisées.

Ajouter Vue 3 ou React

Vue 3

npm install vue
npm install -D @vitejs/plugin-vue

// vite.config.js
import { defineConfig } from 'vite'
import tailwindcss from '@tailwindcss/vite'
import vue from '@vitejs/plugin-vue'

export default defineConfig({
    root: 'resources',
    plugins: [tailwindcss(), vue()],
    // ... reste inchangé
})

// resources/js/app.js
import { createApp } from 'vue'
import MonComposant from './components/MonComposant.vue'

createApp(MonComposant).mount('#app')

<!-- Dans une vue Astral -->
<div id="app"></div>

React

npm install react react-dom
npm install -D @vitejs/plugin-react

// vite.config.js
import react from '@vitejs/plugin-react'
export default defineConfig({
    root: 'resources',
    plugins: [tailwindcss(), react()],
    // ... reste inchangé
})

Structure du projet après installation

votre-projet/
├── resources/                    ← Sources front-end (créées depuis stubs/)
│   ├── js/
│   │   ├── app.js               ← Entry point JS
│   │   └── components/
│   │       ├── flash.js
│   │       └── confirm.js
│   └── css/
│       └── app.css              ← Entry point CSS + Tailwind v4
│
├── public/
│   ├── index.php
│   └── build/                   ← Généré par npm run build (gitignored)
│       ├── manifest.json
│       └── assets/
│
├── vendor/
│   └── astral-php/
│       └── astral-vite/         ← Ce package
│           ├── src/
│           │   ├── ViteAssets.php
│           │   └── ViteServiceProvider.php
│           └── stubs/
│
├── vite.config.js               ← Copié depuis stubs/
├── package.json                 ← Copié depuis stubs/
├── node_modules/                ← Généré par npm install (gitignored)
└── .env                         ← VITE_DEV_SERVER + VITE_BUILD_DIR (optionnel)

astral-php / astral-vite

Maintainers

Package info

Statistics

Security

README

Sommaire

Prérequis

Installation

1. Installer le package via Composer

2. Enregistrer le ServiceProvider

3. Configurer le front-end

a) Copier les stubs

b) Installer les dépendances npm

c) Variables .env (optionnel)

4. Utiliser $vite dans le layout

Option 1 — Modifier ton layout existant (`views/layout/main.php`)

Option 2 — Utiliser le layout stub

Alternative (Un seul entry point)

Utilisation quotidienne

Développement

Production

API de ViteAssets

`$vite->tags(string|array $entries): string`

`$vite->asset(string $path): string`

`$vite->isDev(): bool`

Injection dans un contrôleur

Variables d'environnement

Stubs fournis

`flash.js`

`confirm.js`

Comment ça fonctionne

En développement (`APP_ENV=development`)

En production (`APP_ENV=production`)

Ajouter Vue 3 ou React

Vue 3

React

Structure du projet après installation

Licence

astral-php / astral-vite

Maintainers

Package info

Statistics

Security

README

Sommaire

Prérequis

Installation

1. Installer le package via Composer

2. Enregistrer le ServiceProvider

3. Configurer le front-end

a) Copier les stubs

b) Installer les dépendances npm

c) Variables .env (optionnel)

4. Utiliser $vite dans le layout

Option 1 — Modifier ton layout existant (views/layout/main.php)

Option 2 — Utiliser le layout stub

Alternative (Un seul entry point)

Utilisation quotidienne

Développement

Production

API de ViteAssets

$vite->tags(string|array $entries): string

$vite->asset(string $path): string

$vite->isDev(): bool

Injection dans un contrôleur

Variables d'environnement

Stubs fournis

flash.js

confirm.js

Comment ça fonctionne

En développement (APP_ENV=development)

En production (APP_ENV=production)

Ajouter Vue 3 ou React

Vue 3

React

Structure du projet après installation

Licence

Option 1 — Modifier ton layout existant (`views/layout/main.php`)

`$vite->tags(string|array $entries): string`

`$vite->asset(string $path): string`

`$vite->isDev(): bool`

`flash.js`

`confirm.js`

En développement (`APP_ENV=development`)

En production (`APP_ENV=production`)