Come creare uno starter kit per Laravel

Introduzione

Uno starter kit è un progetto template che viene espanso con create-project quando crei un’applicazione con laravel new. Gli starter kit ufficiali di Laravel 13 sono quattro — React / Vue / Svelte / Livewire — e includono autenticazione e UI iniziale. Quando crei il tuo starter kit personalizzato fai la stessa cosa: parti da un’applicazione Laravel, la sistemi e la pubblichi come pacchetto Composer.

Documentazione ufficiale: Starter Kits
Esempio ufficiale: laravel/react-starter-kit
Pagina di riferimento: Laravel Console Starter

Creare lo starter kit

Inizializzare il progetto Laravel

Per prima cosa crei il progetto Laravel che farà da template e ripulisci il codice di esempio superfluo. Poi assegni a name in composer.json un nome di pacchetto univoco.

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

Questo name è l’identificatore che verrà usato poi con laravel new my-app --using=example/starter-kit.

Configurare gli scripts di composer.json

Dopo l’esecuzione di laravel new, gli script Composer dello starter kit vengono utilizzati nel flusso di inizializzazione. Assicurati almeno che siano presenti post-root-package-install e 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"
    ]
}

Questo esempio è basato sul composer.json di laravel/react-starter-kit. Se il tuo kit usa un database, puoi riutilizzarlo così com’è.

Controllare i file distribuiti con .gitattributes

Con export-ignore escludi i file che vuoi tenere nel repository dello starter kit ma non nel progetto generato dell’utente.

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

Per i dettagli consulta l’esempio ufficiale di .gitattributes.

Registrazione su Packagist

Per permettere agli utenti di usarlo con --using è necessaria la registrazione su Packagist.

Prepara un repository pubblico su GitHub

Rendi coerenti il name di composer.json e l’URL del repository, poi pubblica.

Registra su Packagist

Registra il repository su Packagist. Dopo la pubblicazione, example/starter-kit diventa risolvibile.

Indica il comando d'uso nel README

Documenta per gli utenti il comando di installazione:

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

Flusso del comando laravel new

Il NewCommand di laravel/installer, quando è indicato uno starter kit, cambia la destinazione di create-project ed esegue in sequenza i comandi di inizializzazione. Punti da controllare in NewCommand.php:

Scelta del framework frontend

Gli starter kit ufficiali di Laravel 13 offrono React / Vue / Svelte / Livewire, ma il tuo starter kit personalizzato non deve necessariamente adeguarsi a questa configurazione. Puoi scegliere liberamente CSS, component library e metodo di autenticazione in base ai tuoi obiettivi.

Opzione	Configurazione tipica	Casi adatti
Ufficiali React / Vue / Svelte / Livewire	Configurazione ufficiale con Inertia 3 o Livewire 4	Offrire un’esperienza di sviluppo vicina all’ufficiale
Frontend personalizzato	CSS e component library a piacere	Riusare un design system esistente o un’altra base CSS
Kit Blade semplice	Prevalenza di Blade, dipendenze frontend minime	Una configurazione leggera e rapida da introdurre
Kit di autenticazione personalizzato	Non limitato a Fortify (es.: centrato su Socialite)	Restringere a un metodo di autenticazione specifico

Gli starter kit della community di solito adottano basi CSS diverse dall’ufficiale. Anche l’autenticazione non deve necessariamente basarsi su Fortify: progettala in funzione dei tuoi requisiti.

Manutenzione tra versioni

Uno starter kit non è “fatto e finito”. Va aggiornato in modo continuo per stare al passo con Laravel e PHP.

Aggiornamento a nuove versioni di Laravel e PHP

Aggiorna i requisiti in composer.json e verifica la compatibilità in CI.

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

Con gli aggiornamenti major di Laravel, rivedi contestualmente laravel/framework e le dipendenze correlate.

Aggiornamento periodico dei pacchetti

Le dipendenze frontend cambiano rapidamente, quindi è più sicuro attivare un task di aggiornamento mensile.

Tailwind
Component library (shadcn/ui, shadcn-vue, shadcn-svelte, Flux UI)
Pacchetti Inertia / Livewire

Test di compatibilità

Includi almeno queste verifiche in CI.

composer install va a buon fine
php artisan test passa
npm install && npm run build passa

Buone pratiche

Fissa name presto: dopo la pubblicazione su Packagist, cambiarlo ha un costo elevato.
Basati sugli script ufficiali: rompere il flusso di inizializzazione aumenta i fallimenti di installazione.
Definisci subito .gitattributes: riduci il rumore durante la distribuzione del template.
Rendi periodici gli aggiornamenti: crea un’operatività che segua rapidamente le release di Laravel.
Leggi le guide correlate: Sviluppo di pacchetti Laravel e Gestire la compatibilità tra versioni dei pacchetti rendono il design più stabile.

​Introduzione

​Creare lo starter kit

​Inizializzare il progetto Laravel

​Configurare gli scripts di composer.json

​Controllare i file distribuiti con .gitattributes

​Registrazione su Packagist

​Flusso del comando laravel new

​Scelta del framework frontend

​Manutenzione tra versioni

​Aggiornamento a nuove versioni di Laravel e PHP

​Aggiornamento periodico dei pacchetti

​Test di compatibilità

​Buone pratiche

Introduzione

Creare lo starter kit

Inizializzare il progetto Laravel

Configurare gli scripts di composer.json

Controllare i file distribuiti con .gitattributes

Registrazione su Packagist

Flusso del comando laravel new

Scelta del framework frontend

Manutenzione tra versioni

Aggiornamento a nuove versioni di Laravel e PHP

Aggiornamento periodico dei pacchetti

Test di compatibilità

Buone pratiche