skip to content

What are `gradleApi()` and `localGroovy()`, and where would you declare them?

level: middleimportance: nice to knowfreq 25%

answer

  1. plugin authoring notations
  2. gradleApi() = Gradle API jars
  3. localGroovy() = bundled Groovy
  4. buildSrc / included build / plugin project
  5. java-gradle-plugin adds gradleApi() automatically

basics

~10 s

They're dependency notations for building Gradle plugins. gradleApi() puts the Gradle API on the compile classpath; localGroovy() adds the Groovy version bundled with the running Gradle. You declare them in a plugin/buildSrc project's dependencies.

solid answer

~40 s

`gradleApi()` and `localGroovy()` are special **dependency notations** used when authoring Gradle plugins or tasks. `gradleApi()` resolves to the Gradle API jars matching the *currently running* Gradle version, so your plugin code can compile against `Project`, `Task`, etc. `localGroovy()` provides the exact Groovy distribution that Gradle ships with — needed if you write plugin code in Groovy and don't want a separate Groovy dependency. You declare them in a project that builds plugins: typically `buildSrc`, an included build, or a standalone plugin project, against the `implementation`/`compileOnly` configuration. With the `java-gradle-plugin` plugin applied, `gradleApi()` is added automatically, so you rarely declare it by hand there. A caveat: because both pin to the running Gradle's versions, they're version-specific and best used for plugins that run inside that same Gradle.

code

kotlin · 9 lines
kotlin
// build-logic/build.gradle.kts
plugins { `java-gradle-plugin` } // already adds gradleApi()

dependencies {
    // explicit form (redundant under java-gradle-plugin):
    implementation(gradleApi())
    implementation(localGroovy())  // only if writing Groovy plugin code
    testImplementation(gradleTestKit())
}

go deeper

for a junior

Recognize the names as plugin-authoring helpers, not app dependencies.

for a middle

Explain what each provides and that they belong in buildSrc/plugin projects, pinned to the running Gradle.

for a senior

Note the java-gradle-plugin auto-wiring, compileOnly usage, and gradleTestKit for plugin tests.

for a principal

Standardize build-logic packaging (included build vs buildSrc) and convention plugins across the org.

## What they are Both are **dependency notation helper methods** available in `dependencies { }` blocks, intended for building Gradle plugins and custom tasks: - **`gradleApi()`** — returns a dependency on the Gradle public API jars for the version of Gradle that is currently executing the build. This is what lets your plugin code `import org.gradle.api.Project`, implement `Plugin<Project>`, register tasks, etc. - **`localGroovy()`** — returns a dependency on the Groovy libraries bundled with the running Gradle distribution. Useful when your plugin or build logic is written in Groovy and you want to compile/run against exactly Gradle's bundled Groovy rather than pulling a separate Groovy artifact. ## Where you declare them They belong in a project whose job is to produce Gradle build logic: ```kotlin // buildSrc/build.gradle.kts (or a plugin module) dependencies { implementation(gradleApi()) implementation(localGroovy()) } ``` Common hosts: - **`buildSrc`** — the conventional place for shared build logic; its outputs are on every build script's classpath. - **An included build** (`includeBuild("build-logic")`) — the modern, more scalable alternative to buildSrc. - **A standalone plugin project** that you publish. ## Interaction with `java-gradle-plugin` If you apply the `java-gradle-plugin` plugin, it **automatically adds `gradleApi()`** to the appropriate configuration and wires plugin metadata. In that setup you typically don't declare `gradleApi()` manually. For Groovy-based plugins applying the `groovy` plugin alongside, `localGroovy()` ensures the compile classpath has Gradle's Groovy. ## Caveats - Both are **pinned to the running Gradle version**, so they're not portable to arbitrary Gradle runtimes; that's by design for plugins meant to run in that Gradle. - `gradleApi()` is a fairly broad classpath; prefer `compileOnly` where you only need it at compile time, and depend on the **Gradle Test Kit** (`gradleTestKit()`) for functional tests of plugins. They are niche — relevant specifically to plugin/task authoring, not application dependency management.

  • If you apply the `java-gradle-plugin` plugin, do you still need `gradleApi()`?
    No — it adds `gradleApi()` to the plugin's classpath automatically, so declaring it manually is usually redundant.
  • What's a limitation of `gradleApi()`?
    It pins to the currently running Gradle version, so the resulting plugin isn't portable to arbitrary Gradle runtimes; it's meant for plugins running in that same Gradle.

saying these in an interview costs you the question

  • Declaring `gradleApi()` in an application module's dependencies.
  • Confusing `localGroovy()` with a regular `org.codehaus.groovy:groovy` dependency.
  • Forgetting that `java-gradle-plugin` already supplies `gradleApi()`.

context

resolving links…