Créer un starter kit Laravel - Knowledge of Laravel

Introduction

Un starter kit est un projet modèle que laravel new déploie via create-project lors de la création d’une application. Les starter kits officiels de Laravel 13 sont au nombre de quatre — React / Vue / Svelte / Livewire — et incluent authentification et interface de départ. Pour créer votre propre starter kit, le principe est identique : partez d’une application Laravel, préparez-la, puis publiez-la comme package Composer.

Documentation officielle : Starter Kits
Exemple d’implémentation officiel : laravel/react-starter-kit
Page de référence : Laravel Console Starter

Créer le starter kit

Initialiser un projet Laravel

Créez d’abord un projet Laravel qui servira de modèle, puis nettoyez le code d’exemple superflu. Ensuite, attribuez un nom de package unique dans composer.json.

{
    "name": "example/starter-kit",
    "type": "project",
    "require": {
        "php": "^8.3",
        "laravel/framework": "^13.0"
    }
}

Ce name sera l’identifiant utilisé plus tard avec laravel new my-app --using=example/starter-kit.

Configurer les scripts de composer.json

Après un laravel new, ce sont les scripts Composer du starter kit qui prennent en charge le flux d’initialisation. Prévoyez au minimum post-root-package-install et post-create-project-cmd.

"scripts": {
    "post-root-package-install": [
        "@php -r \"file_exists('.env') || copy('.env.example', '.env');\""
    ],
    "post-create-project-cmd": [
        "@php artisan key:generate --ansi",
        "@php -r \"file_exists('database/database.sqlite') || touch('database/database.sqlite');\"",
        "@php artisan migrate --graceful --ansi"
    ]
}

Cet exemple est calqué sur le composer.json de laravel/react-starter-kit. Vous pouvez le reprendre tel quel si votre projet utilise une base de données.

Piloter le contenu distribué via .gitattributes

Excluez avec export-ignore les fichiers que vous voulez conserver dans le dépôt du starter kit mais pas dans le projet généré par l’utilisateur.

LICENSE export-ignore
composer.lock export-ignore
README.md export-ignore

Pour plus de détails, voir l’exemple officiel de .gitattributes.

Enregistrer sur Packagist

Pour que vos utilisateurs puissent l’invoquer via --using, il faut publier sur Packagist.

Préparer un dépôt public sur GitHub

Alignez le name du composer.json et l’URL du dépôt, puis publiez.

Enregistrer sur Packagist

Enregistrez le dépôt sur Packagist. Une fois publié, example/starter-kit devient résolvable.

Documenter la commande dans le README

Indiquez la commande d’installation à vos utilisateurs.

laravel new my-app --using=example/starter-kit

Flux de la commande laravel new

Le NewCommand de laravel/installer bascule la destination de create-project lorsque l’utilisateur désigne un starter kit, puis enchaîne les commandes d’initialisation. Emplacements intéressants dans NewCommand.php :

Choix du framework frontend

Les starter kits officiels de Laravel 13 proposent React / Vue / Svelte / Livewire, mais un starter kit maison n’a pas besoin de s’y aligner. Choisissez librement CSS, bibliothèque de composants et système d’authentification en fonction de vos objectifs.

Choix	Configuration principale	Convient à
Officiel React / Vue / Svelte / Livewire	Configuration officielle avec Inertia 3 ou Livewire 4	Offrir une expérience proche de l’officiel
Frontend personnalisé	CSS et bibliothèque de composants au choix	Utiliser un design system existant ou une autre base CSS
Kit Blade simple	Blade au centre, dépendances frontend minimales	Configuration légère à mise en place rapide
Kit d’authentification maison	Ne se limitant pas à Fortify (par ex. axé Socialite)	Se concentrer sur une méthode d’authentification particulière

Les starter kits communautaires adoptent souvent une base CSS différente de l’officiel. Il n’est pas nécessaire de supposer Fortify pour l’authentification : concevez selon vos besoins.

Maintenance des versions

Un starter kit ne se termine pas à sa création. Suivez en continu les évolutions de Laravel et PHP.

Prise en charge des montées de version Laravel/PHP

Mettez d’abord à jour les exigences dans composer.json et vérifiez la compatibilité en CI.

"require": {
    "php": "^8.3",
    "laravel/framework": "^13.0"
}

Lors d’une mise à jour majeure de Laravel, révisez simultanément laravel/framework et les dépendances périphériques.

Mises à jour régulières des dépendances

Les dépendances frontend évoluent vite ; il est prudent de planifier des mises à jour mensuelles.

Tailwind
Bibliothèques de composants (shadcn/ui, shadcn-vue, shadcn-svelte, Flux UI)
Packages liés à Inertia / Livewire

Tests de compatibilité

Intégrez au minimum les vérifications suivantes en CI.

composer install réussit.
php artisan test passe.
npm install && npm run build passe.

Bonnes pratiques

Figer le name tôt : le coût de changement après publication sur Packagist est élevé.
Se caler sur les exemples officiels pour les scripts : casser le flux d’initialisation multiplie les échecs à l’installation.
Préparer .gitattributes dès le début : réduit le bruit lors de la distribution du modèle.
Périodiser les mises à jour : organisez-vous pour suivre Laravel dès sa sortie.
Lire en parallèle les guides connexes : Les bases du développement de packages et Gestion de la compatibilité de versions de package stabilisent votre conception.

​Introduction

​Créer le starter kit

​Initialiser un projet Laravel

​Configurer les scripts de composer.json

​Piloter le contenu distribué via .gitattributes

​Enregistrer sur Packagist

​Flux de la commande laravel new

​Choix du framework frontend

​Maintenance des versions

​Prise en charge des montées de version Laravel/PHP

​Mises à jour régulières des dépendances

​Tests de compatibilité

​Bonnes pratiques

Introduction

Créer le starter kit

Initialiser un projet Laravel

Configurer les scripts de composer.json

Piloter le contenu distribué via .gitattributes

Enregistrer sur Packagist

Flux de la commande laravel new

Choix du framework frontend

Maintenance des versions

Prise en charge des montées de version Laravel/PHP

Mises à jour régulières des dépendances

Tests de compatibilité

Bonnes pratiques