Cloudflare apre l'accesso a un nuovo registro di moduli per Workers. Prima di dedurne che la vostra applicazione Node.js possa migrare senza adattamenti, occorre identificare ciò che il bundler trasforma, ciò che il motore risolve e quali comportamenti richiedano realmente le vostre dipendenze.
Cosa cambia il nuovo registro
Il 9 settembre 2026 Cloudflare ha annunciato un registro di moduli Workers ricostruito, accessibile con il flag di configurazione esplicito new_module_registry. La pubblicazione descrive in particolare import.meta.url, import.meta.main, import.meta.resolve(), gli specificatori URL, require(esm) e la compilazione differita; l'implementazione precedente resta disponibile. Queste capacità sono quelle annunciate da Cloudflare, non una prova di compatibilità generale con Node.js. [fonte Cloudflare]
Il flag deve essere aggiunto all'elenco di compatibilità esistente, senza sostituirlo. Una configurazione di test può aggiungere new_module_registry all'elenco già presente; non costituisce un comando di distribuzione.
{ "compatibility_flags": ["new_module_registry"] }Questo estratto mostra soltanto il flag da aggiungere. Non sostituisce il file di configurazione completo né i flag già presenti.
Separare il bundler dal motore di esecuzione
Il bundler, lo strumento che assembla i file di codice, può rimuovere, trasformare o raggruppare un'importazione prima che arrivi al motore di esecuzione (runtime). Un import visibile nel sorgente non prova quindi che il registro lo risolverà. Ispezionate l'artefatto prodotto e annotate modalità di costruzione, versioni e opzioni prima di concludere che vi sia una modifica del runtime. Questa separazione completa il nostro articolo sulla catena di costruzione.
Costruire casi di test limitati e osservabili
Preparate un piccolo esempio isolato, o fixture, per ogni meccanismo: URL di modulo con parametri e frammento, import.meta.resolve(), import dinamico, confine tra i moduli JavaScript ESM e CommonJS (due formati di caricamento) ed errore di caricamento. La documentazione workerd descrive la progettazione del registro; per riprodurre un test, fissate il riferimento a42a33b0d43d80b9554d3f9d7f04c153d6b0c45f invece di usare un ramo variabile. [riferimento workerd fissato]
Gli esempi qui sotto e i loro file documentari sono una proposta di test; non sono stati eseguiti in Workers. Non forniscono alcun risultato atteso inventato. Un fallimento deve essere esaminato: può dipendere da una dipendenza, dalla costruzione, dal formato ESM/CommonJS o dall'ambiente, e non solo dal registro.
// url-meta.mjs — exemple documentaire non exécuté dans Workers
export const currentUrl = import.meta.url;
export const isMain = import.meta.main;
export const resolved = import.meta.resolve("./url-meta.mjs?mode=test#fixture");
// Comparer séparément les identités et les erreurs avec chaque registre.
export async function loadVariant() {
return import("./url-meta.mjs?mode=dynamic#fixture");
}
Il protocollo deve annotare l'URL, il ruolo del punto di ingresso, l'identità delle istanze e la classe di errore. Conservate anche un caso di modulo assente e un caso di caricamento CommonJS di un modulo ESM. Una sola verifica di sintassi non convalida nessuno di questi comportamenti in Workers.
| Dipendenza | Meccanismo | Caso testato | Osservazione | Incertezza | Decisione |
|---|---|---|---|---|---|
| Da compilare | Da identificare | Non eseguito | Non misurato | Da qualificare | Da decidere |
Confrontare senza confondere runtime e dipendenze
Usate lo stesso artefatto, le stesse dipendenze e gli stessi ingressi in due configurazioni documentate: registro precedente e attivazione di test. Conservate log, asserzioni ed eventuali trasformazioni del bundle. Questo confronto non promette alcun guadagno di velocità né una migrazione automatica; isola semplicemente la variabile studiata.
Preparate anche il rollback nell'ambiente di test: rimuovete soltanto il flag aggiunto, conservate gli altri flag e annotate i criteri che giustificherebbero di proseguire o fermarsi. La compatibilità Workers si dimostra per applicazione, dipendenza e comportamento utilizzato.