Cloudflare Workers: file statici sotto un percorso dedicato senza riorganizzare le cartelle

Il 28 ottobre 2026 Cloudflare ha introdotto una nuova opzione per Workers Static Assets: i file di un sito possono essere pubblicati sotto un prefisso dell’indirizzo web, per esempio /blog/, senza dover spostare gli stessi file in una sottocartella della build. La modifica interessa soprattutto chi ospita documentazione, un blog o una parte dell’interfaccia accanto a un’applicazione gestita da Workers.

Che problema risolve il nuovo percorso

Un’applicazione può avere una sezione pubblica di documentazione e un’API sullo stesso dominio. Il sito statico, però, non sempre deve essere raggiungibile dalla radice dell’indirizzo: a volte è preferibile servirlo da /docs/ o /blog/.

Una configurazione comune prevedeva di organizzare i file generati in modo che le cartelle riproducessero il percorso pubblico. Con la nuova impostazione, Cloudflare consente di mantenere la struttura della directory di output e applicare il prefisso direttamente al servizio degli asset. Per esempio, un file index.html nella directory di build può essere reso disponibile sotto /blog/ senza creare una seconda cartella blog al suo interno.

La distinzione importante è fra posizione del file nella build e percorso richiesto dal browser: la prima non deve necessariamente cambiare quando si decide il secondo.

Come si configura in Wrangler

Nella configurazione Wrangler la nuova proprietà si chiama assets.base_path. Si usa insieme ad assets.directory: la prima stabilisce il prefisso dell’URL, la seconda identifica dove si trovano i file da distribuire.

L’annuncio ufficiale indica Wrangler dalla versione 4.148.0. Per chi usa invece cloudflare.config.ts, la proprietà equivalente è worker.assets.basePath e richiede cf dalla versione 1.0.0-beta.13. Le due sintassi appartengono a strumenti diversi e non vanno mescolate.

Non si tratta di un nuovo dominio, né di una regola generale che riscrive tutte le richieste gestite dal Worker. È un’impostazione specifica per gli asset statici. Il codice delle API e il loro instradamento continuano a richiedere una configurazione coerente con il resto dell’applicazione.

A chi può servire

La novità è utile per i progetti che distribuiscono una parte statica insieme a servizi dinamici: un portale con guide, una documentazione tecnica sotto /docs/ oppure una sezione informativa separata dall’interfaccia principale.

Può semplificare anche la gestione della build: non occorre introdurre cartelle artificiali soltanto per ottenere un determinato percorso pubblico. Questo non elimina la necessità di controllare il risultato finale. I collegamenti interni, i file CSS e JavaScript e gli URL assoluti generati dal framework devono essere compatibili con il prefisso scelto.

Per i lettori italiani che mantengono più sezioni sotto lo stesso dominio, il vantaggio pratico è poter decidere l’indirizzo pubblico senza cambiare per forza la struttura di distribuzione. Non significa che ogni applicazione possa essere spostata da / a /blog/ senza alcun intervento.

Limiti e controlli prima di distribuire

Cloudflare descrive il comportamento degli asset, ma non promette che la nuova opzione corregga automaticamente tutti i link costruiti dall’applicazione. Prima di distribuire una modifica è quindi opportuno verificare almeno la pagina iniziale, le risorse collegate, i collegamenti relativi, le pagine inesistenti e gli eventuali fallback delle single-page application.

Va controllato anche il rapporto con le regole di routing del Worker: il prefisso degli asset non sostituisce la configurazione delle richieste dinamiche. Se il progetto usa il plugin Vite per Cloudflare, occorre verificare il file di configurazione effettivamente generato dalla build.

Cosa seguire nei prossimi giorni

L’annuncio rende disponibile una configurazione più diretta, ma il suo impatto dipende da come ogni progetto genera gli indirizzi delle risorse. Per chi ha già un sito funzionante non è necessario cambiare subito: conviene provare la nuova opzione in un ambiente di anteprima, confrontare i percorsi HTTP e passare alla distribuzione soltanto dopo i controlli.

La modifica è descritta nel changelog ufficiale Cloudflare del 28 ottobre 2026 e nella documentazione Wrangler. Non sono stati eseguiti test indipendenti di distribuzione per questo articolo.

Redazione Quotidiano Digitale — Sikelia Labs