GraalVM JavaScript スクリプトを初めて書く (2026)

最初の GraalVM JavaScript スクリプトを書く

最初の GraalVM JavaScript スクリプトを書くということは、3つの小さなステップを踏むことを意味します。スクリプトをホストのエントリポイントに登録し、イベントやモジュールにアタッチし、エンジンがロードできるようにスクリプトフォルダに保存します。エンジンは GraalVM Polyglot API 上で動作するため、スクリプトはそのままの JavaScript であり、Java を再コンパイルすることなくリロードされます.

まず必要なこと

エンジンを埋め込むホストプログラム。ホストはGraalVM JavaScriptを同梱し、スクリプトから呼び出せるオブジェクト群を公開し、スクリプトフォルダを監視します。GraalVMを個別にインストールする必要はありません。ホストに同梱されています。ホストから渡されるオブジェクトに対して、プレーンなJavaScriptを書きます。

それらのオブジェクトが何に対応しているかを知っておくと役立ちますが、始めるにはJavaを書く必要はありません。JavaScriptを以前に書いたことがあれば、パターンは馴染み深いでしょう。ホストは、インポートするライブラリのように動作し、それを使ってプログラムの内部にアクセスします。

3つのステップ

1. スクリプトフォルダを見つけてください

   起動時に、ホストは既知のディレクトリからスクリプトを読み込みます。正確なパスについては、ホストのドキュメントをご確認ください。通常は、インストールディレクトリ内の scripts/ フォルダです.

2. スクリプトファイルを作成する

   そのフォルダに新しい .js ファイルを作成してください。ホストは、次にスクリプトをロードするときにそれを検出し、起動時、またはサポートされている場合はリロードコマンドを実行したときに検出します.

3. 登録とフック

   ファイル内に、ホストのエントリーポイントにスクリプトを登録し、その後、イベントに動作を関連付けたり、ホストが認識するモジュールを定義したりします.

はい、これで終わりです。ファイルを保存し、リロードすればスクリプトが実行されます。ビルドステップもコンパイルも、待つ時間もありません。編集してリロードするだけです。

最小限の例

ほとんどのホストは、スクリプトに自身を登録するためのエントリポイントと、JavaScriptとプログラムをブリッジするいくつかのプロキシオブジェクトを渡します。正確な名前はホストによって異なりますが、構造は同じです。最初のスクリプトは通常、自身を宣言し、あるイベントに反応するだけです。

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

ホスト自身のAPIリファレンスで、実際のオブジェクト名とメソッド名を確認してください。重要なのはパターンです。登録し、次にイベントをフックするか、モジュールを定義します。ほとんどのホストはイベントループまたはライフサイクルフックを公開しており、ほとんどのスクリプトは1つにリッスンすることで開始します。

作業中のホットリロード

ファイルを保存し、スクリプトをリロードします（ライブリロードをサポートしていない場合はホストを再起動します）。変更は再ビルドなしで有効になります。この高速なループは、modをコンパイルする代わりにスクリプトを使用する主な理由です。スクリプトは数秒でリロードされますが、コンパイルされたmodは再構築および再起動する必要があります。

簡単な機能を追加したり、動作を調整したりする場合は、スクリプトが最適です。エンジンに深く組み込んだり、新しいプリミティブを公開したりする必要がある場合は、コンパイルされたMODが適しているかもしれません。

スクリプトでできること、できないこと

スクリプトは、ホストが公開しているオブジェクトに対して呼び出しを行うことができますが、それ以外はできません。ホストは、GraalVM Polyglotホストアクセスホワイトリストを通じて、スクリプトがアクセスできるクラスとメソッドを宣言し、デフォルトは拒否されます。これにより、スクリプトは安全で予測可能です。アクセスしたいオブジェクトが公開されていない場合は、ホストが追加する必要があります。スクリプト側からホワイトリストを迂回することはできません.

これはバグではなく、仕様です。これは、スクリプトが誤って（または悪意を持って）内部メソッドを呼び出したり、アクセスすべきでないオブジェクトにアクセスしたりして、ホストを壊すことができないことを意味します。また、ホストの管理者がサポートするものとサポートしないものを明確に制御できることも意味します。

よくある質問