Performance

Redocly runs inside the JVM on GraalJS, so no Node.js is needed. By default GraalJS interprets the JavaScript, which is fine for small descriptions and slow for large ones. The first line each goal logs names the engine in use:

[INFO] Redocly 2.57.0 - JavaScript engine: GraalJS interpreter (add org.graalvm.polyglot:js-isolate-linux-amd64-community to the plugin dependencies for faster runs)

Enable the native isolate

For a 2–3× speed-up, add the native isolate named in that log line as a dependency of the plugin (not of the project):

<plugin>
  <groupId>net.mwalser</groupId>
  <artifactId>openapi-toolkit-maven-plugin</artifactId>
  <version>0.2.0</version>
  <dependencies>
    <dependency>
      <groupId>org.graalvm.polyglot</groupId>
      <artifactId>js-isolate-linux-amd64-community</artifactId>
      <version>25.4.4.1.1</version>
      <type>pom</type>
    </dependency>
  </dependencies>
</plugin>

Platforms: linux-amd64, linux-aarch64, darwin-aarch64, windows-amd64; JDK 21 to 25. On a JDK the isolate does not support, the build logs a warning that names the cause and continues on the interpreter.

Benchmarks

These measurements compare first lint runs in a fresh JVM on four cores, without the one-time warm-up described under Engine selection:

Description	Size	Node	Interpreter	Native isolate
Petstore	17 KB	0.06 s	1.1 s	0.4 s
Twilio API	1.9 MB	1.1 s	18 s	7 s
GitHub REST API	12.9 MB	6 s	90 s	44 s

build-docs renders the reference with React inside the JVM, which costs more than linting:

Description	Node	Interpreter	Native isolate
Petstore	0.4 s	2.3 s	1.6 s
Twilio API	2.1 s	21 s	12 s
GitHub REST API	19 s	223 s	110 s

The GitHub page is 71 MB, as with the Redocly CLI, and rendering it took close to 3 GB of memory. On the interpreter that is JVM heap: give Maven more (MAVEN_OPTS=-Xmx4g) for descriptions of that size. The native isolate manages its own heap.

Engine selection

Which engine runs is decided once per build:

Engine	When	Cost
GraalJS with runtime compilation	Maven runs on a GraalVM JDK whose version matches the embedded GraalJS (25)	none
GraalJS native isolate	the isolate dependency above is present	about 60 MB of downloads, 140 MB extracted to `~/.cache/org.graalvm.polyglot/`
GraalJS interpreter	otherwise (any JDK 21+)	none

The engine and the embedded Redocly code are initialized once per Maven JVM and reused by every goal and module, so the warm-up (about 4 s for the interpreter, 1.4 s for the isolate) is paid once per build. build-docs loads Redoc and React in addition when it first runs (about 4 s for the interpreter, 2.5 s for the isolate).

Isolate troubleshooting

If the isolate dependency is present but cannot start, the build continues on the interpreter and a warning names the cause. Check the JDK version, and that the artifact matches your platform and the GraalJS version in the plugin's POM.
The isolate extracts roughly 140 MB per extraction into ~/.cache/org.graalvm.polyglot/, and the cache can hold several. If the home directory is read-only, set -Dpolyglot.engine.userResourceCache=<writable-directory> in .mvn/jvm.config.