Installer le kit, afficher une page

Temps 1 · séance 1 · ~45 min

Les slides du chapitre (PDF)

• Créer le projet portfolio avec le kit Vue de Laravel 13.
• Lancer composer run dev pendant que vous travaillez, pour que Vite prépare vos pages.
• Écrire une route qui passe une prop à une page Vue.
• Lire cette prop dans le code source de la page.
• Vérifier la page avec un test Pest et enregistrer le travail dans un commit.

1. L'installeur à jour#

Le cours utilise l'installeur Laravel 5.31 ou 5.32. Vérifiez sa version dans un terminal.

laravel --version

Si le numéro est plus ancien, mettez l'installeur à jour. Sous Herd, ouvrez le menu Settings et l'onglet PHP, puis cliquez sur Update à la ligne Laravel Installer. Sous Laragon, mettez-le à jour avec Composer.

composer global update laravel/installer

Fermez le terminal, rouvrez-le, puis relancez laravel --version. Un installeur trop ancien se signale aussi lui-même : au lancement de laravel new, il demande « Would you like to update now? ».

2. Créer le projet#

Placez-vous dans le dossier que votre serveur local rend accessible, comme en 5XCOS.

Sous macOS, avec Herd :

cd ~/Herd

Sous Windows, avec Laragon :

cd C:\laragon\www

Lancez l'installeur. L'option --git crée le dépôt Git du projet, comme au chapitre Installation de 5XCOS.

laravel new portfolio --git

Lancez la commande en même temps que la démonstration. L'installeur pose ses questions une par une. Déplacez-vous avec les flèches et validez avec Entrée.

Question de l'installeur	Votre réponse
Do you want to use a starter kit?	Yes
Which frontend stack should your starter kit use?	Vue
Which authentication provider do you prefer?	Laravel's built-in authentication
Would you like to add teams support to your application?	No
Which testing framework do you prefer?	Pest
Do you want to install Laravel Boost to improve AI assisted coding?	No
Would you like to run npm install and npm run build?	Yes

Le starter kit est le kit présenté au chapitre 1.03. Laravel Boost fournit des consignes aux assistants de code IA, et le cours ne l'utilise pas. Avec un kit, l'installeur choisit SQLite sans poser la question. SQLite garde toute la base dans un seul fichier, database/database.sqlite.

Les mêmes réponses tiennent en une ligne, avec une option par question.

laravel new portfolio --vue --pest --npm --database=sqlite --no-boost --git

L'installeur crée le dossier portfolio, installe les paquets PHP et JavaScript, crée la base et compile une première fois les fichiers du navigateur dans public/build/. Entrez ensuite dans le dossier.

cd portfolio

3. Ouvrir portfolio.test#

Herd ou Laragon servent le projet à l'adresse portfolio.test, comme vos projets de 5XCOS. Avec Herd, la fin de la sortie de l'installeur affiche Open: http://portfolio.test. Si l'adresse ne répond pas sous Laragon, cliquez sur « Stop », puis sur « Start All ».

Ouvrez http://portfolio.test. La page d'accueil du kit s'affiche.

Le fichier .env contient APP_URL=http://localhost:8000. Remplacez cette ligne par APP_URL=http://portfolio.test, comme en 5XCOS. Laravel utilise cette adresse quand il fabrique un lien complet, par exemple l'adresse d'une image au chapitre 1.14.

Ouvrez maintenant un second terminal dans le dossier portfolio et lancez les programmes de développement du projet.

composer run dev

composer run dev lance php artisan dev, comme en 5XCOS. La commande php artisan dev:list liste les programmes qu'elle démarre.

 server php artisan serve .. Illuminate\Foundation\Providers\ArtisanServiceProvider@boot
 queue php artisan queue:listen --tries=1 --timeout=0 .. Illuminate\Foundation\Providers\ArtisanServiceProvider@boot
 vite npm run dev .. Illuminate\Foundation\Providers\ArtisanServiceProvider@boot

 Showing [3] dev commands

Cette sortie vient de Windows. Sur macOS, une quatrième ligne, logs, lance Pail, qui affiche le journal de Laravel. Le programme qui compte aujourd'hui est vite. Il lance npm run dev, qui prépare vos pages Vue pour le navigateur à chaque modification. Vous continuez d'ouvrir le projet à l'adresse portfolio.test.

Laissez ce terminal ouvert pendant toute la séance, et arrêtez-le avec Ctrl+C en partant. Le premier terminal reste libre pour Artisan, les tests et Git.

4. Les fichiers qui servent aujourd'hui#

Le kit contient beaucoup de fichiers. Pour ce chapitre, quatre endroits suffisent.

portfolio/
├── app/Http/Controllers/        vos contrôleurs, à partir du chapitre 1.07
├── resources/js/app.ts          le fichier de démarrage de Vue et d'Inertia
├── resources/js/pages/          une page Vue par fichier
│   ├── Welcome.vue              la page d'accueil du kit
│   ├── Dashboard.vue            le tableau de bord du back-office
│   ├── auth/                    connexion, mot de passe oublié…
│   └── settings/                réglages du compte
└── routes/web.php               les routes des pages

Le kit range aussi ses composants dans resources/js/components et ses mises en page dans resources/js/layouts. Vous les ouvrirez plus tard.

5. Une route, une page, une prop#

La route#

Ouvrez routes/web.php. Le kit y déclare la page d'accueil avec Route::inertia('/', 'Welcome'), un raccourci qui affiche une page Vue. Remplacez cette ligne par une route qui passe une prop à une nouvelle page, Home. Ajoutez use Inertia\Inertia; en haut du fichier.

use Inertia\Inertia;

Route::get('/', function () {
    return Inertia::render('Home', [
        'author' => 'Nora Benali', // votre prénom et votre nom
    ]);
})->name('home');

Écrivez votre nom à la place de celui de l'exemple. Gardez ->name('home') : le logo des pages de connexion du kit mène à la route nommée home.

Inertia::render('Home', …) cherche le fichier resources/js/pages/Home.vue. Le premier argument est le chemin du fichier sous resources/js/pages, sans l'extension .vue.

La page#

Créez resources/js/pages/Home.vue. C'est le composant du chapitre 1.03.

<script setup>
defineProps({
    author: String,
});
</script>

<template>
    <h1>Bonjour, je suis {{ author }}</h1>
</template>

defineProps déclare la prop author, et {{ author }} l'affiche. Le bloc <script setup> n'a pas de lang="ts" : vous écrivez du JavaScript dans vos fichiers.

6. Ce qui casse en premier#

Une erreur 500 sans composer run dev#

La première erreur arrive dès que composer run dev ne tourne pas : un terminal fermé, une pause, une nouvelle séance. Faites l'essai. Arrêtez composer run dev avec Ctrl+C dans le second terminal. Sous Windows, le terminal demande « Terminer le programme de commandes (O/N) ? » : répondez O. Ouvrez ensuite http://portfolio.test.

La page est blanche. Le fichier public/hot donne à Laravel l'adresse de Vite pendant que Vite tourne, et Windows ne l'efface pas à l'arrêt : la page demande ses fichiers à un serveur arrêté. Supprimez public/hot, puis rechargez. Laravel affiche alors une page d'erreur 500 avec ce message.

Unable to locate file in Vite manifest: resources/js/pages/Home.vue.

La vue racine app.blade.php demande à Vite le fichier de la page, vu au chapitre 1.03 : resources/js/pages/{$page['component']}.vue. Quand Vite ne tourne pas, Laravel cherche ce fichier dans public/build/manifest.json, la liste des fichiers compilés par l'installeur. Home.vue n'existait pas lors de cette compilation, donc il n'est pas dans la liste.

Relancez composer run dev dans le second terminal, puis rechargez la page. Tant que Vite tourne, Laravel lui demande directement chaque page, même une page créée il y a dix secondes.

Sans composer run dev, une page créée après la dernière compilation fait une erreur 500, et un public/hot oublié fait une page blanche. Lancez-le avant d'ouvrir votre projet, à chaque séance.

La barre latérale du back-office et une erreur dans la console#

Votre titre n'apparaît pas : la page est blanche. Ouvrez la console des outils de développement avec F12, elle affiche une erreur, précédée d'un avertissement de Vue sur une prop user qui vaut null :

TypeError: Cannot read properties of null (reading 'name')

Le kit a tenté d'entourer votre page de la barre latérale de son back-office, avec « Platform » et « Dashboard », et c'est cette barre qui plante. En développement, Vue arrête le dessin de la page à la première erreur, d'où la page blanche. Avec une version compilée par npm run build, Vue continue malgré l'erreur et la barre latérale apparaît autour de votre titre :

Une mise en page, ou layout, est un composant qui entoure une page : barre latérale, en-tête, pied de page. Le kit choisit le layout de chaque page dans resources/js/app.ts, d'après le nom de la page.

layout: (name) => {
    switch (true) {
        case name === 'Welcome':
            return null;
        case name.startsWith('auth/'):
            return AuthLayout;
        case name.startsWith('settings/'):
            return [AppLayout, SettingsLayout];
        default:
            return AppLayout;
    }
},

Welcome ne reçoit aucun layout, null. Les pages de connexion reçoivent AuthLayout. Toutes les autres pages reçoivent AppLayout, le layout du back-office, et Home aussi. Ce layout affiche le nom de l'utilisateur connecté dans la barre latérale. Un visiteur n'est pas connecté, auth.user vaut null, et la lecture de name échoue.

Modifiez la première condition pour que Home soit traitée comme Welcome.

case name === 'Welcome' || name === 'Home':
    return null;

C'est la seule ligne du kit que vous changez dans ce chapitre. Le fichier est en TypeScript, mais cette ligne ne contient aucun type et se lit comme du JavaScript. Rechargez : la page affiche « Bonjour, je suis » suivi de votre nom, sans barre latérale. Le layout public de votre portfolio arrive au chapitre 1.08.

7. La prop dans le navigateur#

Ouvrez le code source de la page avec Ctrl+U, ou Cmd+Option+U sur macOS. Cherchez data-page.

<script data-page="app" type="application/json">{"component":"Home","props":{"errors":{},"name":"Laravel","auth":{"user":null},"sidebarOpen":true,"author":"Nora Benali"},"url":"\/","version":"4927d70f24a6b79ccc312d79f1e3bc91","sharedProps":["errors","name","auth","sidebarOpen"]}

Votre prop author est à la fin de props, avec votre nom. Les quatre autres sont les props partagées du kit, présentées au chapitre 1.03 et listées à la fin, dans sharedProps. Votre version sera différente : elle dépend de vos fichiers compilés.

Pendant que composer run dev tourne, le code source contient aussi déjà votre titre <h1>. En développement, le plugin d'Inertia pour Vite prépare la page une première fois côté serveur. Vous y reviendrez au chapitre 1.19, avec les aperçus de liens partagés.

8. Le piège de la prop name#

Pour afficher votre nom, name semble le meilleur nom de prop. Essayez-le : remplacez 'author' par 'name' dans la route. Le JSON de la page devient celui-ci.

{"component":"Home","props":{"errors":{},"name":"Nora Benali","auth":{"user":null},"sidebarOpen":true},…,"sharedProps":["errors","name","auth","sidebarOpen"]}

La prop name existe déjà. Le kit l'ajoute à chaque page dans app/Http/Middleware/HandleInertiaRequests.php.

public function share(Request $request): array
{
    return [
        ...parent::share($request),
        'name' => config('app.name'),
        'auth' => [
            'user' => $request->user(),
        ],
        'sidebarOpen' => ! $request->hasCookie('sidebar_state') || $request->cookie('sidebar_state') === 'true',
    ];
}

La méthode share renvoie les props partagées. name y vaut le nom de l'application, Laravel tant que vous ne changez pas APP_NAME dans .env. Votre prop porte le même nom, donc elle écrase la prop partagée sur cette page. Tout composant qui lit name reçoit alors votre nom au lieu du nom de l'application. Le logo de la barre latérale du back-office en fait partie : sans la ligne ajoutée dans app.ts, la barre latérale entoure votre page et son logo affiche votre nom.

Ne donnez jamais à une prop le nom d'une prop partagée : name, auth, sidebarOpen ou errors. Remettez 'author' dans la route.

9. Le test#

Créez le fichier tests/Feature/HomeTest.php.

<?php

use Inertia\Testing\AssertableInertia as Assert;

test('home page shows the author name', function () {
    $this->get('/')
        ->assertOk()
        ->assertInertia(fn (Assert $page) => $page
            ->component('Home')
            ->where('author', 'Nora Benali')
        );
});

Écrivez dans where le même nom que dans la route. assertInertia lit l'objet de page de la réponse, sans navigateur. component('Home') vérifie le nom de la page, et where('author', …) vérifie la valeur de la prop.

php artisan test tests/Feature/HomeTest.php

   PASS  Tests\Feature\HomeTest
  ✓ home page shows the author name                                                                              0.37s

  Tests:    1 passed (10 assertions)
  Duration: 0.69s

Le test passe parce que composer run dev tourne. Sans lui, lancez npm run build, qui recompile les fichiers dans public/build/, avant les tests. Sinon, l'erreur de la section 6 revient.

Lancez ensuite toute la suite avec php artisan test. Les tests du kit doivent rester verts avec le vôtre.

10. Le premier commit#

L'option --git a créé le dépôt pendant l'installation. Enregistrez votre travail comme vous le faites depuis 5XCOS, depuis l'interface de VS Code ou en ligne de commande, avec un message comme « Page d'accueil avec le nom de l'auteur ». Le dossier public/build/ et les fichiers générés par Wayfinder n'apparaissent pas dans les changements : .gitignore les exclut, parce qu'ils se recréent avec npm. Créez ensuite un dépôt vide nommé portfolio sur GitHub, sans README, et poussez-y votre travail.

11. À vous#

Temps annoncé : 15 minutes.

Si votre projet n'existe pas encore, faites les sections 2 à 10. Ensuite, vérifiez chaque critère.

• laravel --version affiche 5.31 ou plus.
• Le projet portfolio s'ouvre à l'adresse http://portfolio.test.
• composer run dev tourne dans un terminal à part.
• http://portfolio.test affiche « Bonjour, je suis » suivi de votre nom, sans barre latérale.
• La console des outils de développement ne montre aucune erreur.
• Le code source de la page contient "author": suivi de votre nom.
• La prop s'appelle author, pas name.
• php artisan test tests/Feature/HomeTest.php affiche 1 passed, et php artisan test reste vert.
• Votre commit est fait, et le dépôt est sur GitHub.

À retenir#

• laravel new portfolio --vue --pest --npm --database=sqlite --no-boost --git crée le portfolio avec le kit Vue.
• Herd ou Laragon servent le projet sur portfolio.test, et composer run dev doit tourner pendant que vous travaillez.
• Inertia::render('Home', ['author' => …]) affiche resources/js/pages/Home.vue, qui déclare la prop avec defineProps.
• Une nouvelle page publique s'ajoute à la condition qui renvoie null dans app.ts, sinon elle reçoit le layout du back-office.
• Une prop ne porte jamais le nom d'une prop partagée du kit : name, auth, sidebarOpen ou errors.