Deploy delle App con Cascade

In questa lezione ci concentriamo su come effettuare il deploy di applicazioni utilizzando la funzionalità App Deploys di Windsurf tramite lo strumento Cascade.

In particolare: vedremo a cosa serve, i provider supportati, il processo passo-passo, la configurazione del progetto, l’uso vero e proprio e alcune considerazioni importanti come sicurezza, limiti di utilizzo, troubleshooting. Alla fine dell’esercitazione saremo in grado di pubblicare rapidamente un’app web o sito statico direttamente dal nostro ambiente Windsurf.

A cosa serve App Deploys di Cascade

La funzionalità App Deploys presente in Cascade ci permette di pubblicare un sito web o un’applicazione JavaScript direttamente a un URL pubblico, semplicemente interagendo con l’interfaccia di Cascade. Inoltre, consente di effettuare il redeployment della stessa applicazione dopo eventuali modifiche al codice, mantenendo così la versione online sempre aggiornata.

Un’ulteriore possibilità è quella di “consegnare” o “claimare” il progetto al nostro account personale. Nel caso in cui desideriamo portare la gestione del deploy sotto il nostro controllo diretto e gestirne in autonomia gli aspetti operativi.

In sostanza, questo flusso semplifica notevolmente il passaggio dal codice locale allo stato “pubblicato online”, eliminando la necessità di configurare manualmente pipeline CI/CD o infrastrutture di deploy complesse. Si tratta quindi di una soluzione particolarmente adatta alla creazione di prototipi, anteprime o demo da condividere rapidamente.

Tuttavia, è importante ricordare che, come specificato nella documentazione ufficiale, App Deploys è pensato principalmente per scopi di anteprima (preview). Per applicazioni destinate alla produzione o che gestiscono dati sensibili, Windsurf consiglia di utilizzare un flusso di distribuzione più robusto e completamente gestito dal provider.

Utilizzo pratico: Deploy passo-passo

Mettiamo in pratica il flusso. Immaginiamo di avere una semplice app React pronta alla pubblicazione. Nel pannello Cascade, scriviamo qualcosa come:

“Deploy this project to Netlify”

Durante questa fase, il sistema crea in autonomia i file necessari per la pubblicazione su Netlify: in particolare il file netlify.toml che contiene le impostazioni di build e distribuzione del sito, e il file .gitignore, utile per escludere dal pacchetto di deploy tutti i file non indispensabili.

Una volta completata questa configurazione, Cascade ci informa che è pronto a procedere con il deploy del sito statico e ci mostra una finestra di conferma.

In questa finestra viene indicato il dominio pubblico che sarà assegnato alla nostra applicazione, ad esempio https://modern-static-website-2025.windsurf.build, attraverso il quale potremo accedere al progetto una volta pubblicato.

Sotto la sezione di conferma troviamo un riepilogo delle operazioni che stanno per essere eseguite: vengono mostrati i file che verranno caricati (in questo caso tre) e ci viene chiesto di confermare l’azione cliccando su “Deploy”.
Con questa scelta, autorizziamo Windsurf a creare una nuova app su Netlify e accettiamo automaticamente i termini di servizio associati al deploy. In pochi istanti, la nostra applicazione sarà disponibile online, pronta per essere condivisa o testata.

Cascade caricherà i nostri file sui server di Windsurf, e avvierà la creazione del deploy su Netlify. Dovremo attendere che la build si completi.

Nel caso di errori di build, Cascade presenterà i log della build oppure ci inviterà a “claimare” il progetto per vedere i log direttamente nel provider.

Al termine, riceveremo un URL pubblico come nome-progetto.windsurf.build che possiamo condividere. Inoltre, ci verrà fornito un link per “claimare” il progetto, ovvero trasferirne la proprietà all’account Netlify nostro o aziendale. 

Se successivamente modifichiamo il codice (aggiungiamo funzionalità, correggiamo bug) e vogliamo aggiornare l’app, possiamo semplicemente chiedere a Cascade:

“Update my deployment”

E Cascade userà il file windsurf_deployment.yaml per identificare il deploy precedente e ri-eseguire il processo di update in modo coerente.

Provider e framework supportati per l'uso di Cascade

Attualmente, secondo la documentazione ufficiale di Windsurf, il principale provider supportato da App Deploys è Netlify. Una piattaforma ampiamente utilizzata per l’hosting di siti statici e applicazioni web moderne.

Quando eseguiamo un deploy attraverso Cascade, l’applicazione viene pubblicata su Netlify tramite un’integrazione preconfigurata che gestisce automaticamente la creazione del sito, la build e l’assegnazione di un URL pubblico del tipo <nome-progetto>.windsurf.build. Questo approccio consente di ottenere rapidamente un ambiente online funzionante senza dover impostare manualmente credenziali o configurazioni di hosting.

Al momento, Windsurf utilizza Netlify come provider predefinito per garantire semplicità e stabilità del processo. La documentazione lascia però intendere che in futuro saranno introdotti ulteriori provider, ampliando così le possibilità di scelta e offrendo maggiore flessibilità a chi desidera utilizzare infrastrutture diverse o integrate con pipeline personalizzate.

Il file netlify.toml

Il file netlify.toml è un file di configurazione utilizzato da Netlify per definire come deve essere costruito, gestito e distribuito un sito web o un’applicazione. In altre parole, è una sorta di “guida” che indica a Netlify che cosa deve fare durante il processo di deploy.

Nel contesto di Windsurf e Cascade, questo file viene generato automaticamente quando chiediamo di pubblicare un progetto su Netlify. Serve a specificare le impostazioni di base del progetto, ad esempio quale comando eseguire per la build, quale cartella deve essere pubblicata e quali regole o redirect devono essere applicati.

Un esempio semplificato di netlify.toml potrebbe essere:

[build]
  command = "npm run build"
  publish = "dist"
[[redirects]]
  from = "/*"
  to = "/index.html"
  status = 200

In questo caso, il file indica a Netlify di eseguire il comando npm run build per generare i file del sito epubblicare i contenuti presenti nella cartella dist,

Vengono poi gestite le rotte tramite un redirect verso index.html (utile per applicazioni single-page come quelle in React o Vue).

In sintesi, netlify.toml è il cuore della configurazione del deploy su Netlify. Permette di controllare in modo preciso il comportamento dell’applicazione durante la pubblicazione e il funzionamento online, garantendo che tutto venga distribuito correttamente.

Conclusioni

In questa lezione abbiamo esplorato in modo approfondito il processo di deploy delle applicazioni con Windsurf tramite Cascade, scoprendo come questa funzionalità semplifichi la pubblicazione di un progetto web, trasformandola in un’operazione fluida e accessibile anche a chi non ha esperienza con pipeline di distribuzione complesse.

Abbiamo visto che App Deploys nasce per facilitare il passaggio dal codice locale a un sito o un’applicazione online, eliminando la necessità di configurazioni manuali o interventi tecnici sul server. Grazie all’integrazione con Netlify, attualmente il provider principale supportato, Windsurf è in grado di gestire automaticamente la creazione dei file di configurazione, come il netlify.toml e il .gitignore, e di avviare la pubblicazione del progetto con un semplice comando o richiesta all’interno di Cascade.

Il tutto avviene in pochi passaggi: l’analisi della struttura del progetto, la generazione dei file di supporto, la verifica della configurazione e infine la pubblicazione sul dominio dedicato del tipo <nome-progetto>.windsurf.build.