/graalvm-native-image

name: graalvm-native-image
description: Provides expert guidance for building GraalVM Native Image executables from Java applications. Use when converting JVM applications to native binaries, optimizing cold start times, reducing memory footprint, configuring native build tools for Maven or Gradle, resolving reflection and resource issues in native builds, or implementing framework-specific native support for Spring Boot, Quarkus, and Micronaut. Triggers include "graalvm native image", "native executable java", "java cold start optimization", "native build tools", "ahead of time compilation java", "reflection config graalvm", "native image build failure".
allowed-tools: Read, Write, Edit, Bash, Glob, Grep

GraalVM Native Image for Java Applications

Expert skill for building high-performance native executables from Java applications using GraalVM Native Image, dramatically reducing startup time and memory consumption.

Overview

GraalVM Native Image compiles Java applications ahead-of-time (AOT) into standalone native executables. These executables start in milliseconds, require significantly less memory than JVM-based deployments, and are ideal for serverless functions, CLI tools, and microservices where fast startup and low resource usage are critical.

This skill provides a structured workflow to migrate JVM applications to native binaries, covering build tool configuration, framework-specific patterns, reflection metadata management, and an iterative approach to resolving native build failures.

When to Use

Use this skill when:

• Converting a JVM-based Java application to a GraalVM native executable
• Optimizing cold start times for serverless or containerized deployments
• Reducing memory footprint (RSS) of Java microservices
• Configuring Maven or Gradle with GraalVM Native Build Tools
• Resolving `ClassNotFoundException`, `NoSuchMethodException`, or missing resource errors in native builds
• Generating or editing `reflect-config.json`, `resource-config.json`, or other GraalVM metadata files
• Using the GraalVM tracing agent to collect reachability metadata
• Implementing `RuntimeHints` for Spring Boot native support
• Building native images with Quarkus or Micronaut

Instructions

1. Contextual Project Analysis

Before any configuration, analyze the project to determine the build tool, framework, and dependencies:

**Detect the build tool:**

# Check for Maven
if [ -f "pom.xml" ]; then
    echo "Build tool: Maven"
    # Check for Maven wrapper
    [ -f "mvnw" ] && echo "Maven wrapper available"
fi

# Check for Gradle
if [ -f "build.gradle" ] || [ -f "build.gradle.kts" ]; then
    echo "Build tool: Gradle"
    [ -f "build.gradle.kts" ] && echo "Kotlin DSL"
    [ -f "gradlew" ] && echo "Gradle wrapper available"
fi

**Detect the framework by analyzing dependencies:**

• **Spring Boot**: Look for `spring-boot-starter-*` in `pom.xml` or `build.gradle`
• **Quarkus**: Look for `quarkus-*` dependencies
• **Micronaut**: Look for `micronaut-*` dependencies
• **Plain Java**: No framework dependencies detected

**Check the Java version:**

java -version 2>&1
# GraalVM Native Image requires Java 17+ (recommended: Java 21+)

**Identify potential native image challenges:**

• Reflection-heavy libraries (Jackson, Hibernate, JAXB)
• Dynamic proxy usage (JDK proxies, CGLIB)
• Resource bundles and classpath resources
• JNI or native library dependencies
• Serialization requirements

2. Build Tool Configuration

Configure the appropriate build tool plugin based on the detected environment.

**For Maven projects**, add a dedicated `native` profile to keep the standard build clean. See the [Maven Native Profile Reference](references/maven-native-profile.md) for full configuration.

Key Maven setup:

<profiles>
  <profile>
    <id>native</id>
    <build>
      <plugins>
        <plugin>
          <groupId>org.graalvm.buildtools</groupId>
          <artifactId>native-maven-plugin</artifactId>
          <version>0.10.6</version>
          <extensions>true</extensions>
          <executions>
            <execution>
              <id>build-native</id>
              <goals>
                <goal>compile-no-fork</goal>
              </goals>
              <phase>package</phase>
            </execution>
          </executions>
          <configuration>
            <imageName>${project.artifactId}</imageName>
            <buildArgs>
              <buildArg>--no-fallback</buildArg>
            </buildArgs>
          </configuration>
        </plugin>
      </plugins>
    </build>
  </profile>
</profiles>

Build with: `./mvnw -Pnative package`

**For Gradle projects**, apply the `org.graalvm.buildtools.native` plugin. See the [Gradle Native Plugin Reference](references/gradle-native-plugin.md) for full configuration.

Key Gradle setup (Kotlin DSL):

plugins {
    id("org.graalvm.buildtools.native") version "0.10.6"
}

graalvmNative {
    binaries {
        named("main") {
            imageName.set(project.name)
            buildArgs.add("--no-fallback")
        }
    }
}

Build with: `./gradlew nativeCompile`

3. Framework-Specific Configuration

Each framework has its own AOT strategy. Apply the correct configuration based on the detected framework.

**Spring Boot** (3.x+): Spring Boot has built-in GraalVM support with AOT processing. See the [Spring Boot Native Reference](references/spring-boot-native.md) for patterns including `RuntimeHints`, `@RegisterReflectionForBinding`, and test support.

Key points:

• Use `spring-boot-starter-parent` 3.x+ which includes the native profile
• Register reflection hints via `RuntimeHintsRegistrar`
• Run AOT processing with `process-aot` goal
• Build with: `./mvnw -Pnative native:compile` or `./gradlew nativeCompile`

**Quarkus and Micronaut**: These frameworks are designed native-first and require minimal additional configuration. See the [Quarkus & Micronaut Reference](references/quarkus-micro