Écrivez votre premier script JavaScript GraalVM (2026)

Écrivez Votre Premier Script JavaScript GraalVM

Écrire un premier script JavaScript GraalVM implique trois petites étapes : enregistrer le script avec le point d'entrée de l'hôte, l'attacher à un événement ou un module, et le sauvegarder dans le dossier des scripts afin que le moteur le charge. Le moteur fonctionne sur l'API polyglotte GraalVM, donc le script est du JavaScript réel et se recharge sans recompilation de Java.

Ce dont vous avez d'abord besoin

Un programme hôte qui intègre le moteur. L'hôte est fourni avec GraalVM JavaScript, expose un ensemble d'objets que les scripts peuvent appeler et surveille un dossier de scripts. Vous n'installez pas GraalVM vous-même ; l'hôte l'inclut. Vous écrivez du JavaScript standard en utilisant les objets que l'hôte vous fournit.

Connaître la correspondance de ces objets est utile, mais vous n'avez pas besoin d'écrire du Java pour commencer. Si vous avez déjà écrit du JavaScript, le schéma vous sera familier : l'hôte agit comme une bibliothèque que vous importez, et vous l'utilisez pour accéder aux entrailles du programme.

Les trois étapes

1. Trouvez le dossier scripts

   L'hôte charge les scripts à partir d'un répertoire connu au démarrage. Consultez la documentation de l'hôte pour connaître le chemin exact. Généralement, il s'agit d'un dossier scripts/ dans le répertoire d'installation.

2. Créez un fichier script

   Créez un nouveau fichier .js dans ce dossier. L'hôte le détectera lors de la prochaine exécution des scripts, que ce soit au démarrage ou lors d'une commande de rechargement si elle est prise en charge.

3. Enregistrez et accrochez

   Dans le fichier, enregistrez le script avec le point d'entrée de l'hôte, puis associez un comportement à un événement ou définissez un module que l'hôte reconnaît.

C'est tout. Enregistrez le fichier, rechargez et le script s'exécute. Pas d'étape de compilation, pas de compilation, pas d'attente. Éditez et rechargez simplement.

Un exemple minimal

La plupart des environnements d'exécution fournissent un script avec un point d'entrée unique pour s'enregistrer et quelques objets proxy qui permettent de faire le lien entre JavaScript et le programme. Les noms exacts dépendent de l'environnement d'exécution, mais la structure est la même. Un premier script annonce généralement sa présence et réagit à un seul événement :

// 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.");
});

Consultez la documentation de l'API de l'environnement d'exécution pour connaître les noms réels des objets et des méthodes. L'idée est le schéma : enregistrement, puis accrochage d'un événement ou définition d'un module. La plupart des environnements d'exécution exposent une boucle d'événements ou un crochet de cycle de vie, et la plupart des scripts commencent par écouter l'un d'eux.

Rechargement à chaud pendant que vous travaillez

Enregistrez le fichier et rechargez les scripts (ou redémarrez l'environnement d'exécution s'il ne prend pas en charge le rechargement en direct). La modification prend effet sans recompilation. Cette boucle rapide est la principale raison de préférer un script à un module compilé : un script se recharge en quelques secondes, tandis qu'un module compilé doit être reconstruit et relancé.

Si vous ajoutez une fonctionnalité simple ou si vous modifiez un comportement, le scripting est la solution. Si vous devez accéder en profondeur au moteur ou exposer de nouveaux éléments primitifs, un mod compilé pourrait être plus approprié.

Ce que les scripts peuvent et ne peuvent pas faire

Un script peut appeler les objets que l’hôte expose, et rien d’autre. L’hôte déclare les classes et les méthodes auxquelles les scripts peuvent accéder via la liste blanche d’accès hôte polyglotte GraalVM, et par défaut, l’accès est refusé. Cela permet de maintenir les scripts en sécurité et prévisibles. Si l’objet que vous souhaitez n’est pas exposé, l’hôte doit l’ajouter ; vous ne pouvez pas dépasser la liste blanche depuis le script.

C'est une fonctionnalité, pas un bug. Cela signifie que les scripts ne peuvent pas, par inadvertance (ou malveillance), casser l'hôte en appelant des méthodes internes ou en accédant à des objets auxquels ils ne devraient pas. Cela signifie également que les responsables de l'hôte ont un contrôle clair sur ce qui est pris en charge et ce qui ne l'est pas.

FAQ