Scrivi il tuo primo script JavaScript GraalVM (2026)

Scrivi il Tuo Primo Script JavaScript GraalVM

Scrivere il tuo primo script JavaScript GraalVM significa tre semplici passaggi: registrare lo script con il punto di ingresso dell'host, associarlo a un evento o modulo e salvarlo nella cartella degli script in modo che l'engine lo carichi. L'engine funziona tramite l'API Polyglot di GraalVM, quindi lo script è JavaScript reale e si ricarica senza ricompilare alcun codice Java.

Cosa ti serve innanzitutto

Un programma host che integra il motore. L'host include GraalVM JavaScript, espone un insieme di oggetti che gli script possono chiamare e monitora una cartella degli script. Non devi installare GraalVM separatamente; l'host lo include. Scrivi JavaScript standard contro gli oggetti che l'host ti fornisce.

Conoscere a cosa corrispondono quegli oggetti aiuta, ma non devi scrivere alcun codice Java per iniziare. Se hai già scritto JavaScript, lo schema ti risulterà familiare: l'host si comporta come una libreria che importi, e lo usi per accedere agli interni del programma.

I tre passaggi

1. Trova la cartella script

   L'host carica gli script da una directory nota all'avvio. Consultare la documentazione dell'host per il percorso esatto. Di solito si tratta di una cartella scripts/ nella directory di installazione.

2. Crea un file script

   Crea un nuovo file .js in quella cartella. L'host lo rileverà al prossimo caricamento degli script, all'avvio o quando esegui un comando di ricaricamento, se supportato.

3. Registra e aggancia

   All'interno del file, registra lo script con il punto di ingresso dell'host, quindi associa un comportamento a un evento o definisci un modulo che l'host riconosca.

Ecco fatto. Salva il file, ricarica e lo script è in esecuzione. Nessun passaggio di build, nessuna compilazione, nessuna attesa. Modifica e ricarica.

Un esempio minimale

La maggior parte degli host fornisce a uno script un punto di ingresso per registrarsi e alcuni oggetti proxy che collegano JavaScript al programma. I nomi esatti dipendono dall'host, ma la struttura è la stessa. Uno script iniziale di solito si annuncia e reagisce a un solo evento:

// Register the script with the host.
script.register({
  name: "hello-world",
  version: "1.0.0",
});
 
// React to an event the host exposes.
script.on("enable", () => {
  client.print("Hello from my first script.");
});

Leggi la documentazione API dell'host per i nomi reali degli oggetti e dei metodi. Il punto è il pattern: registra, poi collega un evento o definisci un modulo. La maggior parte degli host espone un ciclo di eventi o un hook del ciclo di vita, e la maggior parte degli script inizia ascoltando uno.

Ricaricamento a caldo mentre lavori

Salva il file e ricarica gli script (o riavvia l'host se non supporta il live reload). La modifica ha effetto senza ricostruire. Questo ciclo veloce è il motivo principale per cui scriptare invece di compilare una mod: uno script si ricarica in secondi, mentre una mod compilata deve essere ricostruita e rilanciata.

Se stai aggiungendo una funzionalità semplice o modificando un comportamento, lo scripting è la strada da seguire. Se hai bisogno di interagire a fondo con il motore o di esporre nuovi primitivi, un mod compilato potrebbe essere una soluzione.

Cosa possono e non possono fare gli script

Uno script può chiamare gli oggetti che l'host espone e nient'altro. L'host dichiara quali classi e metodi gli script possono utilizzare tramite la whitelist di accesso poliglota GraalVM, e l'impostazione predefinita è il diniego. Questo mantiene gli script sicuri e prevedibili. Se l'oggetto che desideri non è esposto, l'host deve aggiungerlo; non puoi superare la whitelist dal lato script.

Questa è una funzionalità, non un difetto. Significa che gli script non possono accidentalmente (o in modo malevolo) compromettere il sistema ospite chiamando metodi interni o accedendo a oggetti a cui non dovrebbero. Significa anche che i manutentori del sistema ospite hanno un controllo chiaro su ciò che è supportato e su ciò che non lo è.

FAQ