Build Plugins: One-Line HKJ Setup

Before and After

Without the Plugin

A manual setup requires dependencies, annotation processors, the compile-time checker, and preview flags wired into every task that needs them. The full build file runs to roughly 30 lines -- see Manual Gradle and Maven Setup for the complete configuration.

With the Plugin

// build.gradle.kts
plugins {
    id("io.github.higher-kinded-j.hkj") version "0.3.7-SNAPSHOT"
}

That is it. The plugin handles dependencies, preview flags, compile-time checks, and Javadoc configuration automatically.

Using SNAPSHOT Versions

SNAPSHOT versions of the plugin are published to the Sonatype snapshots repository. Add it to pluginManagement in your settings.gradle.kts:

// settings.gradle.kts
pluginManagement {
    repositories {
        maven {
            url = uri("https://central.sonatype.com/repository/maven-snapshots/")
        }
        gradlePluginPortal()
        mavenCentral()
    }
}

You also need the same repository in your project's repositories block so the plugin can resolve HKJ library dependencies:

// build.gradle.kts
repositories {
    mavenCentral()
    maven {
        url = uri("https://central.sonatype.com/repository/maven-snapshots/")
    }
}

Extension DSL Reference

The plugin creates an hkj extension block with these options:

hkj {
    version = "0.3.7-SNAPSHOT"       // HKJ library version (default: plugin version)
    preview = true           // add --enable-preview flags (default: true)
    spring = false           // add hkj-spring-boot-starter (default: false)
    skills = false           // install Claude Code skills (default: false)
    checks {
        pathTypeMismatch = true   // enable compile-time Path type checking (default: true)
    }
}

Defaults

With default settings, the plugin adds:

• hkj-core to implementation
• hkj-processor-plugins to annotationProcessor
• hkj-checker to annotationProcessor
• --enable-preview to JavaCompile, Test, JavaExec, and Javadoc tasks
• -Xplugin:HKJChecker to compiler arguments

Spring Boot Mode

Enable Spring Boot integration to add the HKJ Spring Boot starter:

hkj {
    spring = true
}

This adds hkj-spring-boot-starter to the implementation configuration, which provides auto-configuration for using HKJ types with Spring's dependency injection and web layer.

Claude Code Skills

Install six Claude Code skills that provide contextual, in-editor guidance for HKJ:

hkj {
    skills = true
}

This runs the hkjInstallSkills task during every build, copying skill files into .claude/skills/. You can also run the task manually:

./gradlew hkjInstallSkills

Version Management

By default, the plugin uses its own published version for HKJ dependencies. Override this to pin a different version:

hkj {
    version = "0.2.2"    // use an older version
}

All HKJ dependencies (hkj-core, hkj-processor-plugins, hkj-checker, hkj-spring-boot-starter) use the same version.

Disabling Features

Disable Preview Features

If your project manages preview flags separately:

hkj {
    preview = false
}

Disable Compile-Time Checks

To skip Path type mismatch detection:

hkj {
    checks {
        pathTypeMismatch = false
    }
}

This removes hkj-checker from the annotation processor path and omits the -Xplugin:HKJChecker compiler argument.

Maven Users

With the HKJ Maven Plugin

The HKJ Maven plugin provides similar automation to the Gradle plugin. Add it with <extensions>true</extensions> so it can configure dependencies and compiler settings automatically:

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>io.github.higher-kinded-j</groupId>
            <artifactId>hkj-bom</artifactId>
            <version>0.3.7-SNAPSHOT</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

<build>
    <plugins>
        <plugin>
            <groupId>io.github.higher-kinded-j</groupId>
            <artifactId>hkj-maven-plugin</artifactId>
            <version>0.3.7-SNAPSHOT</version>
            <extensions>true</extensions>
        </plugin>
    </plugins>
</build>

The plugin automatically adds hkj-core, annotation processors, compile-time checks, and preview feature flags. Configure options in the <configuration> block:

<configuration>
    <version>0.3.7-SNAPSHOT</version>   <!-- HKJ library version (default: plugin version) -->
    <preview>true</preview>              <!-- add --enable-preview flags (default: true) -->
    <spring>false</spring>               <!-- add hkj-spring-boot-starter (default: false) -->
    <skills>false</skills>               <!-- install Claude Code skills (default: false) -->
    <pathTypeMismatch>true</pathTypeMismatch>  <!-- enable compile-time checks (default: true) -->
</configuration>

Run diagnostics with mvn hkj:diagnostics or install skills with mvn hkj:install-skills.

Manual Maven Setup

Projects that cannot apply the Maven plugin should see Manual Gradle and Maven Setup for the full pom.xml -- including the BOM, annotation processors, the HKJChecker compiler plugin, and the preview flags for surefire and exec plugins.

Previous: Manual Gradle and Maven Setup Next: Compile-Time Checks