Repository files navigation

GraalJS is a JavaScript engine implemented in Java on top of GraalVM.It is an ECMAScript-compliant runtime to execute JavaScript and Node.js applications, and includes all the benefits from the GraalVM stack including interoperability with Java.GraalJS is an open-source project.

The goals of GraalJS are:

• Full compatibility with the latest ECMAScript specification
• Interoperability with Java
• Interoperability with WebAssembly using the JavaScript WebAssembly API
• Running JavaScript with the best possible performance
• Support for Node.js applications, including native packages
• Simple upgrading from applications based onNashorn orRhino
• Embeddability in systems likeOracle RDBMS or MySQL

As of version 23.1.0, GraalJS is available asMaven artifacts.We also providestandalone distributions of the JavaScript and Node.js runtimes.

Thanks to GraalJS, you can easily embed JavaScript into a Java application.All necessary artifacts can be downloaded directly from Maven Central.

All artifacts relevant to embedders can be found in the Maven dependency grouporg.graalvm.polyglot.

Below is a minimal Maven dependency setup that you can copy into yourpom.xml:

<dependency>    <groupId>org.graalvm.polyglot</groupId>    <artifactId>polyglot</artifactId>    <version>${graaljs.version}</version></dependency><dependency>    <groupId>org.graalvm.polyglot</groupId>    <artifactId>js</artifactId>    <version>${graaljs.version}</version>    <type>pom</type></dependency>

This enables GraalJS which is built on top of Oracle GraalVM and licensed under theGraalVM Free Terms and Conditions (GFTC).Usejs-community if you want to use GraalJS built on GraalVM Community Edition.

To accesspolyglot isolate artifacts (GFTC only), use the-isolate suffix instead (e.g.js-isolate).

See thepolyglot embedding demonstration on GitHub for a complete runnable example.

You can use GraalJS with GraalVM JDK, Oracle JDK, or OpenJDK.If you prefer running on a stock JVM, have a look atRun GraalJS on a Stock JDK.Note that in this mode many features and optimizations of GraalVM are not available.Due to those limitations, running on a stock JVM is not a supported feature - please use a GraalVM instead.

Standalone distributions are published onGitHub.There are two language runtime options to choose from:

• Native launcher compiled ahead of time with GraalVM Native Image;
• JVM-based runtime.

To distinguish between them, a standalone that comes with a JVM has a-jvm infix in the name.Also, the GraalVM Community Edition version has-community in the name, for example,graaljs-community-<version>-<os>-<arch>.tar.gz.

Four different configurations are available for each component and platform combination:

To install GraalJS from a standalone, download and extract the archive from theGitHub Releases page.After the installation, thejs ornode executable in thebin subdirectory can be used to run JavaScript files or Node modules, respectively.If no file is provided on the command line, an interactive shell (REPL) will be spawned.

Note: If you are using macOS, first remove the quarantine attribute from the archive:shell sudo xattr -r -d com.apple.quarantine <archive>.tar.gz

GraalJS can run unmodified Node.js applications.GraalVM's Node.js runtime is based on a recent version of Node.js, and runs the GraalJS engine instead of Google V8.It provides high compatibility with the existing NPM packages.This includes NPM packages with native implementations.Note that some NPM modules may require to be recompiled from source with GraalJS (if they ship with binaries that have been compiled for Node.js based on V8).

Node.js is available as a separatestandalone distribution.Seehow to get started with Node.js.

Extensive user documentation is available on thewebsite.In addition, there is documentation in this repository underdocs, forusers andcontributors.For contributing, see also aguide on how to build GraalJS from source code.

GraalJS is compatible with theECMAScript 2024 specification.New features, new ECMAScript proposals, scheduled to land in future editions, are added frequently and are accessible behind an option.See theCHANGELOG.md for the proposals already adopted.

In addition, some popular extensions of other engines are supported. SeeGraalJS Compatibility.

The core JavaScript engine is a Java application and is thus compatible with every operating system that provides a compatible JVM. SeeRun GraalJS on a Stock JDK.We provide binary distributions and fully support GraalJS on Linux (x64, AArch64), macOS (x64, AArch64), and Windows (x64), currently.

Seegraalvm.org/community for how to stay connected with the development community.The channelgraaljs ongraalvm.slack.com is a good way to get in touch with the team behind GraalJS.Report any GraalJS-specific issues at theoracle/graaljs GitHub repository.

GraalJS source code and community distributions are available under theUniversal Permissive License (UPL), Version 1.0.

Non-community artifacts are provided under theGraalVM Free Terms and Conditions (GFTC) including License for Early Adopter Versions.