Escreva Seu Primeiro Script JavaScript GraalVM (2026)

Escreva o Seu Primeiro Script JavaScript GraalVM

Escrever o primeiro script JavaScript GraalVM significa três pequenas etapas: registrar o script com o ponto de entrada do host, anexá-lo a um evento ou módulo e salvá-lo na pasta de scripts para que o motor o carregue. O motor funciona com a API Poliglota GraalVM, então o script é JavaScript real e recarrega sem recompilar nenhum Java.

O que você precisa primeiro

Um programa host que incorpora o engine. O host é fornecido com o GraalVM JavaScript, expõe um conjunto de objetos para os scripts chamarem e monitora uma pasta de scripts. Você não instala o GraalVM por conta própria; o host o inclui. Você escreve JavaScript simples contra os objetos que o host fornece.

Saber a que esses objetos correspondem ajuda, mas você não precisa escrever nenhum Java para começar. Se você já escreveu JavaScript antes, o padrão será familiar: o host funciona como uma biblioteca que você importa e o usa para acessar os internos do programa.

Os três passos

1. Encontre a pasta de scripts

   O host carrega scripts de um diretório conhecido na inicialização. Consulte a documentação do host para obter o caminho exato. Geralmente é uma pasta scripts/ no diretório de instalação.

2. Crie um ficheiro de script

   Crie um novo arquivo .js nessa pasta. O host o detecta na próxima vez que carrega os scripts, seja na inicialização ou quando você executa um comando de recarregamento, se suportado.

3. Registrar e fisgar

   Dentro do arquivo, registre o script com o ponto de entrada do host, em seguida, associe um comportamento a um evento ou defina um módulo que o host reconheça.

É isso. Salve o arquivo, recarregue e o script é executado. Sem etapa de compilação, sem compilação, sem espera. Apenas edite e recarregue.

Um exemplo mínimo

A maioria dos hosts fornece a um script um ponto de entrada para se registrar e alguns objetos proxy que conectam JavaScript ao programa. Os nomes exatos dependem do host, mas a estrutura é a mesma. Um primeiro script geralmente apenas se anuncia e reage a um 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.");
});

Leia a própria referência da API do host para os nomes reais dos objetos e métodos. O ponto é o padrão: registrar, então conectar um evento ou definir um módulo. A maioria dos hosts expõe um loop de eventos ou um hook de ciclo de vida, e a maioria dos scripts começa ouvindo um.

Recarregamento a quente enquanto você trabalha

Salve o arquivo e recarregue os scripts (ou reinicie o host se ele não suportar o recarregamento ao vivo). A alteração entra em vigor sem reconstrução. Este loop rápido é a principal razão para usar scripts em vez de compilar um mod: um script é recarregado em segundos, enquanto um mod compilado precisa ser reconstruído e relançado.

Se você está adicionando um recurso simples ou ajustando o comportamento, a criação de scripts é o caminho. Se você precisa se integrar profundamente ao motor ou expor primitivos novos, um mod compilado pode fazer sentido.

O que os scripts podem e não podem fazer

Um script pode chamar os objetos que o host expõe e nada mais. O host declara quais classes e métodos os scripts podem acessar por meio da lista de permissões de acesso poliglota GraalVM, e o padrão é negar. Isso mantém os scripts seguros e previsíveis. Se o objeto que você deseja não estiver exposto, o host precisa adicioná-lo; você não pode ultrapassar a lista de permissões do lado do script.

Este é um recurso, não um defeito. Significa que os scripts não podem, acidentalmente (ou maliciosamente), comprometer o sistema hospedeiro ao chamar métodos internos ou acessar objetos que não deveriam. Também significa que os responsáveis pela manutenção do sistema hospedeiro têm controle claro sobre o que é suportado e o que não é.

Perguntas Frequentes