Prologo

Primi Passi

Architettura

Le Basi

Approfondimenti

Sicurezza

Database

Eloquent ORM

Testing

Package

Vite

Introduzione

Vite è uno strumento di build frontend moderno che offre un ambiente di sviluppo estremamente veloce e raggruppa il tuo codice per la produzione. Quando costruisci applicazioni con Laravel, solitamente utilizzerai Vite per raggruppare i file CSS e JavaScript della tua applicazione in asset pronti per la produzione.

Laravel si integra perfettamente con Vite fornendo un plugin ufficiale e una direttiva Blade per caricare i tuoi asset in sviluppo e in produzione.

Stai usando Laravel Mix? Vite ha sostituito Laravel Mix nelle nuove installazioni di Laravel. Per la documentazione di Mix, visita il sito Laravel Mix. Se desideri passare a Vite, consulta la nostra guida alla migrazione.

Scegliere tra Vite e Laravel Mix

Prima di passare a Vite, le nuove applicazioni Laravel utilizzavano Mix, basato su webpack, per il bundling delle risorse. Vite si concentra su un’esperienza più veloce e produttiva nella creazione di applicazioni JavaScript complesse. Se stai sviluppando una Single Page Application (SPA), comprese quelle create con strumenti come Inertia, Vite è la scelta ideale.

Vite funziona bene anche con applicazioni tradizionali renderizzate lato server con qualche "sprazzo" di JavaScript, incluse quelle che usano Livewire. Tuttavia, manca di alcune funzionalità supportate da Laravel Mix, come la possibilità di copiare risorse arbitrarie nel build che non sono direttamente referenziate nella tua applicazione JavaScript.

Migrare nuovamente a Mix

Hai iniziato una nuova applicazione Laravel usando il nostro scaffolding Vite ma hai bisogno di tornare a Laravel Mix e webpack? Nessun problema. Consulta la nostra guida ufficiale sulla migrazione da Vite a Mix.

Installazione e Configurazione

La documentazione seguente spiega come installare e configurare manualmente il plugin Laravel Vite. Tuttavia, i vari starter kits di Laravel includono già tutto questo scaffolding e sono il modo più veloce per iniziare con Laravel e Vite.

Installazione di Node

Devi assicurarti che Node.js (16+) e NPM siano installati prima di eseguire Vite e il plugin Laravel:

node -v
npm -v

Puoi facilmente installare l’ultima versione di Node e NPM utilizzando semplici installer grafici dal sito ufficiale di Node. Oppure, se usi Laravel Sail, puoi invocare Node e NPM tramite Sail:

./vendor/bin/sail node -v
./vendor/bin/sail npm -v

Installazione di Vite e del Plugin Laravel

In una nuova installazione di Laravel, troverai un file package.json nella cartella principale della tua applicazione. Il file package.json predefinito include già tutto il necessario per iniziare a usare Vite e il plugin Laravel. Puoi installare le dipendenze frontend della tua applicazione tramite NPM:

npm install

Configurare Vite

Vite è configurato tramite un file vite.config.js nella radice del tuo progetto. Puoi personalizzare questo file secondo le tue esigenze e installare altri plugin necessari per la tua applicazione, come @vitejs/plugin-vue o @vitejs/plugin-react.

Il plugin Laravel Vite richiede di specificare i punti di ingresso della tua applicazione. Questi possono essere file JavaScript o CSS e includono linguaggi preprocessati come TypeScript, JSX, TSX e Sass.

import { defineConfig } from 'vite';
import laravel from 'laravel-vite-plugin';

export default defineConfig({
    plugins: [
        laravel([
            'resources/css/app.css',
            'resources/js/app.js',
        ]),
    ],
});

Se stai creando una SPA, inclusi applicazioni costruite con Inertia, Vite funziona meglio senza punti di ingresso CSS:

import { defineConfig } from 'vite';
import laravel from 'laravel-vite-plugin';

export default defineConfig({
    plugins: [
        laravel([
            'resources/css/app.css', // [tl! remove]
            'resources/js/app.js',
        ]),
    ],
});

Invece, dovresti importare il tuo CSS tramite JavaScript. Tipicamente, questo viene fatto nel file resources/js/app.js della tua applicazione:

import './bootstrap';
import '../css/app.css'; // [tl! add]

Il plugin Laravel supporta anche più punti di ingresso e opzioni di configurazione avanzate come punti di ingresso SSR.

Lavorare con un Server di Sviluppo Sicuro

Se il tuo server web di sviluppo locale serve la tua applicazione tramite HTTPS, potresti riscontrare problemi nel connetterti al server di sviluppo Vite.

Se stai utilizzando Laravel Herd e hai messo in sicurezza il sito oppure stai usando Laravel Valet e hai eseguito il comando secure sulla tua applicazione, il plugin Laravel Vite rileverà automaticamente e utilizzerà il certificato TLS generato per te.

Se hai messo in sicurezza il sito usando un host che non corrisponde al nome della directory dell’applicazione, puoi specificare manualmente l’host nel file vite.config.js della tua applicazione:

import { defineConfig } from 'vite';
import laravel from 'laravel-vite-plugin';

export default defineConfig({
    plugins: [
        laravel({
            // ...
            detectTls: 'my-app.test', // [tl! add]
        }),
    ],
});

Quando usi un altro server web, dovresti generare un certificato attendibile e configurare manualmente Vite per utilizzare i certificati generati:

// ...
import fs from 'fs'; // [tl! add]

const host = 'my-app.test'; // [tl! add]

export default defineConfig({
    // ...
    server: { // [tl! add]
        host, // [tl! add]
        hmr: { host }, // [tl! add]
        https: { // [tl! add]
            key: fs.readFileSync(`/path/to/${host}.key`), // [tl! add]
            cert: fs.readFileSync(`/path/to/${host}.crt`), // [tl! add]
        }, // [tl! add]
    }, // [tl! add]
});

Se non riesci a generare un certificato attendibile per il tuo sistema, puoi installare e configurare il @vitejs/plugin-basic-ssl plugin. Quando usi certificati non attendibili, dovrai accettare l’avviso del certificato per il server di sviluppo di Vite nel tuo browser seguendo il link "Local" nel terminale quando esegui il comando npm run dev.

Avviare il server di sviluppo in Sail su WSL2

Quando utilizzi il server di sviluppo Vite all’interno di Laravel Sail su Windows Subsystem for Linux 2 (WSL2), devi aggiungere la seguente configurazione nel tuo file vite.config.js per assicurarti che il browser possa comunicare con il server di sviluppo:

// ...

export default defineConfig({
    // ...
    server: { // [tl! add:start]
        hmr: {
            host: 'localhost',
        },
    }, // [tl! add:end]
});

Se le modifiche ai file non vengono riflesse nel browser mentre il server di sviluppo è in esecuzione, potrebbe essere necessario configurare anche l’opzione server.watch.usePolling di Vite.

Caricamento dei tuoi Script e Stili

Con i tuoi punti di ingresso Vite configurati, ora puoi riferirli in una direttiva Blade @vite() che aggiungi all’<head> del template principale della tua applicazione:

<!DOCTYPE html>
<head>
    {{-- ... --}}

    @vite(['resources/css/app.css', 'resources/js/app.js'])
</head>

Se stai importando il tuo CSS tramite JavaScript, devi includere solo il punto di ingresso JavaScript:

<!DOCTYPE html>
<head>
    {{-- ... --}}

    @vite('resources/js/app.js')
</head>

La direttiva @vite rileverà automaticamente il server di sviluppo Vite e inietterà il client Vite per abilitare l’Hot Module Replacement. In modalità build, la direttiva caricherà i tuoi asset compilati e versionati, inclusi eventuali CSS importati.

Se necessario, puoi anche specificare il percorso di build dei tuoi asset compilati quando invochi la direttiva @vite:

<!doctype html>
<head>
    {{-- Il percorso di build dato è relativo al percorso pubblico. --}}

    @vite('resources/js/app.js', 'vendor/courier/build')
</head>

Inline Assets

A volte può essere necessario includere il contenuto "grezzo" delle risorse invece di collegarsi all’URL versionata della risorsa. Ad esempio, potresti dover inserire direttamente il contenuto delle risorse nella tua pagina quando passi contenuti HTML a un generatore di PDF. Puoi mostrare il contenuto delle risorse Vite utilizzando il metodo content fornito dalla facade Vite:

@use('Illuminate\Support\Facades\Vite')

<!doctype html>
<head>
    {{-- ... --}}

    <style>
        {!! Vite::content('resources/css/app.css') !!}
    </style>
    <script>
        {!! Vite::content('resources/js/app.js') !!}
    </script>
</head>

Eseguire Vite

Ci sono due modi per eseguire Vite. Puoi avviare il server di sviluppo tramite il comando dev, che è utile durante lo sviluppo locale. Il server di sviluppo rileverà automaticamente le modifiche ai tuoi file e le rifletterà istantaneamente in qualsiasi finestra del browser aperta.

Oppure, eseguire il comando build versionerà e raggrupperà le risorse della tua applicazione, preparandole per essere distribuite in produzione:

# Avvia il server di sviluppo Vite...
npm run dev

# Compila e versiona le risorse per la produzione...
npm run build

Se stai eseguendo il server di sviluppo in Sail su WSL2, potresti aver bisogno di alcune opzioni di configurazione aggiuntive.

Lavorare con JavaScript

Alias

Di default, il plugin Laravel fornisce un alias comune per aiutarti a partire subito e importare comodamente le risorse della tua applicazione:

{
    '@' => '/resources/js'
}

Puoi sovrascrivere l’alias '@' aggiungendo il tuo nel file di configurazione vite.config.js:

import { defineConfig } from 'vite';
import laravel from 'laravel-vite-plugin';

export default defineConfig({
    plugins: [
        laravel(['resources/ts/app.tsx']),
    ],
    resolve: {
        alias: {
            '@': '/resources/ts',
        },
    },
});

Vue

Se vuoi costruire il frontend usando il framework Vue, dovrai anche installare il plugin @vitejs/plugin-vue:

npm install --save-dev @vitejs/plugin-vue

Successivamente puoi includere il plugin nel file di configurazione vite.config.js. Ci sono alcune opzioni aggiuntive necessarie quando utilizzi il plugin Vue con Laravel:

import { defineConfig } from 'vite';
import laravel from 'laravel-vite-plugin';
import vue from '@vitejs/plugin-vue';

export default defineConfig({
    plugins: [
        laravel(['resources/js/app.js']),
        vue({
            template: {
                transformAssetUrls: {
                    // Il plugin Vue riscriverà gli URL delle risorse, quando vengono referenziati
                    // nei Single File Components, per puntare al server web di Laravel.
                    // Impostando questo su `null` permette al plugin Laravel
                    // di riscrivere invece gli URL delle risorse per puntare al server di Vite.
                    base: null,

                    // Il plugin Vue analizzerà gli URL assoluti e li tratterà
                    // come percorsi assoluti ai file sul disco. Impostando questo su
                    // `false` lascerà gli URL assoluti invariati in modo che possano
                    // riferirsi correttamente alle risorse nella directory pubblica.
                    includeAbsolute: false,
                },
            },
        }),
    ],
});

I vari starter kits di Laravel includono già la configurazione corretta per Laravel, Vue e Vite. Dai un’occhiata a Laravel Breeze per iniziare rapidamente con Laravel, Vue e Vite.

React

Se desideri costruire il frontend utilizzando il framework React, dovrai anche installare il plugin @vitejs/plugin-react:

npm install --save-dev @vitejs/plugin-react

Successivamente, puoi includere il plugin nel tuo file di configurazione vite.config.js:

import { defineConfig } from 'vite';
import laravel from 'laravel-vite-plugin';
import react from '@vitejs/plugin-react';

export default defineConfig({
    plugins: [
        laravel(['resources/js/app.jsx']),
        react(),
    ],
});

Dovrai assicurarti che tutti i file contenenti JSX abbiano un’estensione .jsx o .tsx, ricordandoti di aggiornare il punto di ingresso, se necessario, come mostrato sopra.

Dovrai anche includere la direttiva Blade aggiuntiva @viteReactRefresh insieme alla tua direttiva @vite esistente.

@viteReactRefresh
@vite('resources/js/app.jsx')

La direttiva @viteReactRefresh deve essere chiamata prima della direttiva @vite.

I starter kit di Laravel includono già la configurazione corretta per Laravel, React e Vite. Dai un’occhiata a Laravel Breeze per iniziare rapidamente con Laravel, React e Vite.

Inertia

Il plugin Laravel Vite offre una comoda funzione resolvePageComponent per aiutarti a risolvere i componenti di pagina Inertia. Di seguito è riportato un esempio dell’uso dell’helper con Vue 3; tuttavia, puoi utilizzare anche la funzione in altri framework come React:

import { createApp, h } from 'vue';
import { createInertiaApp } from '@inertiajs/vue3';
import { resolvePageComponent } from 'laravel-vite-plugin/inertia-helpers';

createInertiaApp({
  resolve: (name) => resolvePageComponent(`./Pages/${name}.vue`, import.meta.glob('./Pages/**/*.vue')),
  setup({ el, App, props, plugin }) {
    createApp({ render: () => h(App, props) })
      .use(plugin)
      .mount(el)
  },
});

Se stai utilizzando la funzione di code splitting di Vite con Inertia, ti consigliamo di configurare l’asset prefetching.

I starter kits di Laravel includono già la configurazione corretta per Laravel, Inertia e Vite. Dai un’occhiata a Laravel Breeze per il modo più veloce per iniziare con Laravel, Inertia e Vite.

Elaborazione degli URL

Quando si utilizza Vite e si fanno riferimenti a risorse nell’HTML, CSS o JS dell’applicazione, ci sono un paio di aspetti da considerare. Innanzitutto, se si fa riferimento a risorse con un percorso assoluto, Vite non includerà la risorsa nel build; quindi, è necessario assicurarsi che la risorsa sia disponibile nella directory pubblica. Bisogna evitare di usare percorsi assoluti quando si utilizza un punto di ingresso dedicato CSS perché, durante lo sviluppo, i browser cercheranno di caricare questi percorsi dal server di sviluppo di Vite, dove il CSS è ospitato, piuttosto che dalla directory pubblica.

Quando si fa riferimento a percorsi relativi delle risorse, bisogna ricordare che i percorsi sono relativi al file in cui vengono referenziati. Qualsiasi risorsa referenziata tramite un percorso relativo verrà riscritta, versionata e raggruppata da Vite.

Considera la seguente struttura del progetto:

public/
  taylor.png
resources/
  js/
    Pages/
      Welcome.vue
  images/
    abigail.png

Il seguente esempio dimostra come Vite tratterà URL relativi e assoluti:

<!-- Questa risorsa non è gestita da Vite e non sarà inclusa nel build -->
<img src="/taylor.png">

<!-- Questa risorsa sarà riscritta, versionata e raggruppata da Vite -->
<img src="../../images/abigail.png">

Lavorare con gli Stylesheet

Puoi saperne di più sul supporto CSS di Vite nella documentazione di Vite. Se utilizzi plugin PostCSS come Tailwind, puoi creare un file postcss.config.js nella root del tuo progetto e Vite lo applicherà automaticamente:

export default {
    plugins: {
        tailwindcss: {},
        autoprefixer: {},
    },
};

I starter kit di Laravel includono già la configurazione corretta per Tailwind, PostCSS e Vite. Oppure, se desideri usare Tailwind e Laravel senza utilizzare uno dei nostri starter kit, consulta la guida all’installazione di Tailwind per Laravel.

Lavorare con Blade e Route

Elaborazione delle Risorse Statiche con Vite

Quando fai riferimento alle risorse nei tuoi JavaScript o CSS, Vite le elabora e le versiona automaticamente. Inoltre, quando costruisci applicazioni basate su Blade, Vite può anche elaborare e versionare risorse statiche che riferisci solo nei template Blade.

Per fare questo, devi informare Vite delle tue risorse importando le risorse statiche nel punto di ingresso dell’applicazione. Ad esempio, se desideri elaborare e versionare tutte le immagini memorizzate in resources/images e tutti i font memorizzati in resources/fonts, dovresti aggiungere quanto segue nel punto di ingresso resources/js/app.js della tua applicazione:

import.meta.glob([
  '../images/**',
  '../fonts/**',
]);

Queste risorse saranno ora elaborate da Vite durante l’esecuzione di npm run build. Successivamente, puoi fare riferimento a queste risorse nei template Blade utilizzando il metodo Vite::asset, che restituirà l’URL versionato per una determinata risorsa:

<img src="{{ Vite::asset('resources/images/logo.png') }}">

Aggiornamento al Salvataggio

Quando la tua applicazione è costruita utilizzando il rendering tradizionale lato server con Blade, Vite può migliorare il tuo flusso di lavoro di sviluppo aggiornando automaticamente il browser quando apporti modifiche ai file di visualizzazione nella tua applicazione. Per iniziare, puoi semplicemente impostare l’opzione refresh su true.

import { defineConfig } from 'vite';
import laravel from 'laravel-vite-plugin';

export default defineConfig({
    plugins: [
        laravel({
            // ...
            refresh: true,
        }),
    ],
});

Quando l’opzione refresh è true, salvare i file nelle seguenti directory farà sì che il browser esegua un aggiornamento completo della pagina mentre stai eseguendo npm run dev:

  • app/Livewire/**
  • app/View/Components/**
  • lang/**
  • resources/lang/**
  • resources/views/**
  • routes/**

Monitorare la directory routes/** è utile se stai utilizzando Ziggy per generare link di rotte nel frontend della tua applicazione.

Se questi percorsi predefiniti non soddisfano le tue esigenze, puoi specificare una tua lista di percorsi da monitorare:

import { defineConfig } from 'vite';
import laravel from 'laravel-vite-plugin';

export default defineConfig({
    plugins: [
        laravel({
            // ...
            refresh: ['resources/views/**'],
        }),
    ],
});

Sotto il cofano, il plugin Laravel Vite utilizza il pacchetto vite-plugin-full-reload, che offre alcune opzioni di configurazione avanzate per personalizzare il comportamento di questa funzionalità. Se hai bisogno di questo livello di personalizzazione, puoi fornire una definizione di config:

import { defineConfig } from 'vite';
import laravel from 'laravel-vite-plugin';

export default defineConfig({
    plugins: [
        laravel({
            // ...
            refresh: [{
                paths: ['path/to/watch/**'],
                config: { delay: 300 }
            }],
        }),
    ],
});

Alias

È comune nelle applicazioni JavaScript creare alias per directory a cui si fa frequentemente riferimento. Tuttavia, puoi anche creare alias da usare in Blade utilizzando il metodo macro della classe Illuminate\Support\Facades\Vite. Di solito, le "macro" vengono definite all’interno del metodo boot di un service provider:

/**
 * Bootstrap any application services.
 */
public function boot(): void
{
    Vite::macro('image', fn (string $asset) => $this->asset("resources/images/{$asset}"));
}

Una volta definita una macro, può essere utilizzata nei tuoi template. Ad esempio, possiamo usare la macro image definita sopra per fare riferimento a un asset situato in resources/images/logo.png:

<img src="{{ Vite::image('logo.png') }}" alt="Laravel Logo">

Prefetching degli Asset

Quando si costruisce un SPA utilizzando la funzionalità di code splitting di Vite, gli asset necessari vengono recuperati ad ogni navigazione tra le pagine. Questo comportamento può causare un ritardo nel rendering dell’interfaccia utente. Se questo rappresenta un problema per il framework frontend che preferisci, Laravel offre la possibilità di prefetchare anticipatamente gli asset JavaScript e CSS della tua applicazione al caricamento iniziale della pagina.

Puoi istruire Laravel a prefetchare anticipatamente i tuoi asset invocando il metodo Vite::prefetch nel metodo boot di un provider di servizi:

<?php

namespace App\Providers;

use Illuminate\Support\Facades\Vite;
use Illuminate\Support\ServiceProvider;

class AppServiceProvider extends ServiceProvider
{
    /**
     * Registra eventuali servizi dell'applicazione.
     */
    public function register(): void
    {
        // ...
    }

    /**
     * Avvia qualsiasi servizio dell'applicazione.
     */
    public function boot(): void
    {
        Vite::prefetch(concurrency: 3);
    }
}

Nell’esempio sopra, gli asset verranno prefetchati con un massimo di 3 download simultanei ad ogni caricamento della pagina. Puoi modificare la concorrenza per adattarla alle esigenze della tua applicazione oppure specificare nessun limite di concorrenza se l’applicazione deve scaricare tutti gli asset contemporaneamente:

/**
 * Avvia qualsiasi servizio dell'applicazione.
 */
public function boot(): void
{
    Vite::prefetch();
}

Per impostazione predefinita, il prefetching inizierà quando si verifica l’evento load della pagina. Se desideri personalizzare quando inizia il prefetching, puoi specificare un evento a cui Vite ascolterà:

/**
 * Avvia qualsiasi servizio dell'applicazione.
 */
public function boot(): void
{
    Vite::prefetch(event: 'vite:prefetch');
}

Con il codice sopra, il prefetching inizierà quando dispatcherai manualmente l’evento vite:prefetch sull’oggetto window. Ad esempio, potresti far iniziare il prefetching tre secondi dopo il caricamento della pagina:

<script>
    addEventListener('load', () => setTimeout(() => {
        dispatchEvent(new Event('vite:prefetch'))
    }, 3000))
</script>

URL di Base Personalizzate

Se le tue risorse compilate da Vite vengono distribuite su un dominio separato dalla tua applicazione, ad esempio tramite un CDN, devi specificare la variabile d’ambiente ASSET_URL nel file .env della tua applicazione:

ASSET_URL=https://cdn.example.com

Dopo aver configurato l’URL delle risorse, tutti gli URL riscritti per le tue risorse saranno preceduti dal valore configurato:

https://cdn.example.com/build/assets/app.9dce8d17.js

Ricorda che gli URL assoluti non vengono riscritti da Vite, quindi non saranno preceduti dal prefisso.

Variabili d’Ambiente

Puoi inserire variabili d’ambiente nel tuo JavaScript aggiungendo il prefisso VITE_ nel file .env della tua applicazione:

VITE_SENTRY_DSN_PUBLIC=http://example.com

Puoi accedere alle variabili d’ambiente inserite tramite l’oggetto import.meta.env:

import.meta.env.VITE_SENTRY_DSN_PUBLIC

Disabilitare Vite nei Test

L’integrazione di Vite in Laravel cercherà di risolvere le tue risorse durante l’esecuzione dei test, il che richiede di eseguire il server di sviluppo Vite o di compilare le tue risorse.

Se preferisci simulare Vite durante i test, puoi utilizzare il metodo withoutVite, disponibile per tutti i test che estendono la classe TestCase di Laravel:

test('esempio without vite', function () {
    $this->withoutVite();

    // ...
});

use Tests\TestCase;

class ExampleTest extends TestCase
{
    public function test_without_vite_example(): void
    {
        $this->withoutVite();

        // ...
    }
}

Se vuoi disabilitare Vite per tutti i test, puoi chiamare il metodo withoutVite nel metodo setUp della tua classe base TestCase:

<?php

namespace Tests;

use Illuminate\Foundation\Testing\TestCase as BaseTestCase;

abstract class TestCase extends BaseTestCase
{
    protected function setUp(): void// [tl! add:start]
    {
        parent::setUp();

        $this->withoutVite();
    }// [tl! add:end]
}

Rendering lato server (SSR)

Il plugin Laravel Vite rende facile configurare il server-side rendering con Vite. Per iniziare, crea un punto di ingresso SSR in resources/js/ssr.js e specifica il punto di ingresso passando un’opzione di configurazione al plugin Laravel:

import { defineConfig } from 'vite';
import laravel from 'laravel-vite-plugin';

export default defineConfig({
    plugins: [
        laravel({
            input: 'resources/js/app.js',
            ssr: 'resources/js/ssr.js',
        }),
    ],
});

Per assicurarti di non dimenticare di ricostruire il punto di ingresso SSR, ti consigliamo di modificare lo script "build" nel package.json della tua applicazione per creare il build SSR:

"scripts": {
     "dev": "vite",
     "build": "vite build" // [tl! remove]
     "build": "vite build && vite build --ssr" // [tl! add]
}

Poi, per costruire e avviare il server SSR, puoi eseguire i seguenti comandi:

npm run build
node bootstrap/ssr/ssr.js

Se stai usando SSR con Inertia, puoi invece usare il comando Artisan inertia:start-ssr per avviare il server SSR:

php artisan inertia:start-ssr

I starter kit di Laravel includono già la configurazione corretta di Laravel, Inertia SSR e Vite. Dai un’occhiata a Laravel Breeze per il modo più veloce per iniziare con Laravel, Inertia SSR e Vite.

Attributi dei Tag Script e Style

Content Security Policy (CSP) Nonce

Se desideri includere un nonce attribute nei tuoi tag script e style come parte della tua Content Security Policy, puoi generare o specificare un nonce utilizzando il metodo useCspNonce all’interno di un middleware personalizzato:

<?php

namespace App\Http\Middleware;

use Closure;
use Illuminate\Http\Request;
use Illuminate\Support\Facades\Vite;
use Symfony\Component\HttpFoundation\Response;

class AddContentSecurityPolicyHeaders
{
    /**
     * Gestisci una richiesta in arrivo.
     *
     * @param  \Closure(\Illuminate\Http\Request): (\Symfony\Component\HttpFoundation\Response)  $next
     */
    public function handle(Request $request, Closure $next): Response
    {
        Vite::useCspNonce();

        return $next($request)->withHeaders([
            'Content-Security-Policy' => "script-src 'nonce-".Vite::cspNonce()."'",
        ]);
    }
}

Dopo aver invocato il metodo useCspNonce, Laravel includerà automaticamente gli attributi nonce su tutti i tag script e style generati.

Se hai bisogno di specificare il nonce altrove, inclusa la directive Ziggy @route inclusa nei starter kit di Laravel, puoi recuperarlo usando il metodo cspNonce:

@routes(nonce: Vite::cspNonce())

Se hai già un nonce che desideri che Laravel utilizzi, puoi passarlo al metodo useCspNonce:

Vite::useCspNonce($nonce);

Integrità delle Sottorisorse (SRI)

Se il tuo manifest di Vite include gli hash integrity per le tue risorse, Laravel aggiungerà automaticamente l’attributo integrity a tutti i tag script e style che genera per applicare l’Integrità delle Sottorisorse. Per impostazione predefinita, Vite non include l’hash integrity nel suo manifest, ma puoi abilitarlo installando il plugin NPM vite-plugin-manifest-sri:

npm install --save-dev vite-plugin-manifest-sri

Puoi poi abilitare questo plugin nel tuo file vite.config.js:

import { defineConfig } from 'vite';
import laravel from 'laravel-vite-plugin';
import manifestSRI from 'vite-plugin-manifest-sri';// [tl! add]

export default defineConfig({
    plugins: [
        laravel({
            // ...
        }),
        manifestSRI(),// [tl! add]
    ],
});

Se necessario, puoi anche personalizzare la chiave del manifest dove si trova l’hash di integrità:

use Illuminate\Support\Facades\Vite;

Vite::useIntegrityKey('custom-integrity-key');

Se desideri disabilitare completamente questa rilevazione automatica, puoi passare false al metodo useIntegrityKey:

Vite::useIntegrityKey(false);

Attributi Arbitrari

Se hai bisogno di aggiungere attributi extra ai tuoi tag script e style, come l’attributo data-turbo-track, puoi specificarli usando i metodi useScriptTagAttributes e useStyleTagAttributes. Di solito, questi metodi devono essere chiamati da un provider di servizi:

use Illuminate\Support\Facades\Vite;

Vite::useScriptTagAttributes([
    'data-turbo-track' => 'reload', // Specifica un valore per l'attributo...
    'async' => true, // Specifica un attributo senza valore...
    'integrity' => false, // Escludi un attributo che altrimenti verrebbe incluso...
]);

Vite::useStyleTagAttributes([
    'data-turbo-track' => 'reload',
]);

Se hai bisogno di aggiungere attributi in modo condizionale, puoi passare una funzione che riceverà il percorso della sorgente dell’asset, la sua URL, il chunk del manifest e l’intero manifest:

use Illuminate\Support\Facades\Vite;

Vite::useScriptTagAttributes(fn (string $src, string $url, array|null $chunk, array|null $manifest) => [
    'data-turbo-track' => $src === 'resources/js/app.js' ? 'reload' : false,
]);

Vite::useStyleTagAttributes(fn (string $src, string $url, array|null $chunk, array|null $manifest) => [
    'data-turbo-track' => $chunk && $chunk['isEntry'] ? 'reload' : false,
]);

Gli argomenti $chunk e $manifest saranno null mentre il server di sviluppo Vite è in esecuzione.

Personalizzazione Avanzata

Di default, il plugin Vite di Laravel utilizza convenzioni sensate che dovrebbero funzionare per la maggior parte delle applicazioni; tuttavia, a volte potrebbe essere necessario personalizzare il comportamento di Vite. Per abilitare opzioni di personalizzazione aggiuntive, offriamo i seguenti metodi e opzioni che possono essere usati al posto della direttiva Blade @vite:

<!doctype html>
<head>
    {{-- ... --}}

    {{
        Vite::useHotFile(storage_path('vite.hot')) // Personalizza il file "hot"...
            ->useBuildDirectory('bundle') // Personalizza la directory di build...
            ->useManifestFilename('assets.json') // Personalizza il nome del file del manifest...
            ->withEntryPoints(['resources/js/app.js']) // Specifica i punti di ingresso...
            ->createAssetPathsUsing(function (string $path, ?bool $secure) { // Personalizza la generazione del percorso backend per le risorse buildate...
                return "https://cdn.example.com/{$path}";
            })
    }}
</head>

Nel file vite.config.js, dovresti quindi specificare la stessa configurazione:

import { defineConfig } from 'vite';
import laravel from 'laravel-vite-plugin';

export default defineConfig({
    plugins: [
        laravel({
            hotFile: 'storage/vite.hot', // Personalizza il file "hot"...
            buildDirectory: 'bundle', // Personalizza la directory di build...
            input: ['resources/js/app.js'], // Specifica i punti di ingresso...
        }),
    ],
    build: {
      manifest: 'assets.json', // Personalizza il nome del file del manifest...
    },
});

Correggere gli URL del Server di Sviluppo

Alcuni plugin nell’ecosistema Vite presumono che gli URL che iniziano con una barra (forward-slash) puntino sempre al server di sviluppo di Vite. Tuttavia, a causa dell’integrazione con Laravel, non è così.

Ad esempio, il plugin vite-imagetools genera URL come il seguente mentre Vite serve le tue risorse:

<img src="/@imagetools/f0b2f404b13f052c604e632f2fb60381bf61a520">

Il plugin vite-imagetools si aspetta che l’URL generato venga intercettato da Vite e che il plugin gestisca tutti gli URL che iniziano con /@imagetools. Se usi plugin che richiedono questo comportamento, dovrai correggere manualmente gli URL. Puoi farlo nel tuo file vite.config.js utilizzando l’opzione transformOnServe.

In questo esempio, aggiungeremo l’URL del server di sviluppo a tutte le occorrenze di /@imagetools nel codice generato:

import { defineConfig } from 'vite';
import laravel from 'laravel-vite-plugin';
import { imagetools } from 'vite-imagetools';

export default defineConfig({
    plugins: [
        laravel({
            // ...
            transformOnServe: (code, devServerUrl) => code.replaceAll('/@imagetools', devServerUrl+'/@imagetools'),
        }),
        imagetools(),
    ],
});

Ora, mentre Vite serve le risorse, genererà URL che puntano al server di sviluppo di Vite:

- <img src="/@imagetools/f0b2f404b13f052c604e632f2fb60381bf61a520"><!-- [tl! remove] -->
+ <img src="http://[::1]:5173/@imagetools/f0b2f404b13f052c604e632f2fb60381bf61a520"><!-- [tl! add] -->
Lascia un commento

Lascia un commento

Il tuo indirizzo email non sarà pubblicato. I campi obbligatori sono contrassegnati *

Laravel-Italia.it è il sito della Community Italiana di Laravel.
2024 — Laravel-Italia