---
title: Registering Gradle plugins in Arciphant components
description: Combine Arciphant with convention plugins for components and included builds.
icon: blocks
sidebar:
  label: Using Plugins
---

:::info[Project layout only]
Gradle plugins can only be applied to projects, so registering them in the Arciphant DSL works only in the
[project layout](/component-layouts), where every component and bundle is its own Gradle project — everything on this
page applies to that layout. In the source set layout, convention plugins are applied in the `build.gradle.kts` of each
module or bundle project instead and configure the components via
[shared dependency configurations](/component-layouts#shared-dependency-configurations).
:::

## Component plugins

The real power of Arciphant comes into play when you use it in combination with convention plugins that configure your
components' characteristics and external dependencies. Convention plugins define what a component _type_ looks like;
Arciphant defines which components exist and how they relate — see
[Beyond convention plugins](/#beyond-convention-plugins) for how the two complement each other.

Convention plugins are pre-compiled script plugins that contain build logic. See
the [official Gradle documentation](https://docs.gradle.org/current/userguide/implementing_gradle_plugins_precompiled.html)
for detailed information. They can be located either in the `buildSrc` folder or in a separate Gradle project that is
included with `includeBuild` in `pluginManagement`.

Assume that each of the components in your modules has some specific Gradle setup, such as external dependencies and
the configuration around them. For example, the web component might depend on a web framework, and the db component on
a library that manages database access.

So assume you have the following convention plugins in your `buildSrc` folder specifying the dependencies/configurations
for the respective component types:

- `spring-web-component.gradle.kts`
- `jooq-component.gradle.kts`

Such a convention plugin is a plain precompiled script plugin — it applies the JVM plugin and declares whatever the
component type needs, for example:

```kotlin buildSrc/src/main/kotlin/spring-web-component.gradle.kts
plugins {
    kotlin("jvm")
}

dependencies {
    implementation("org.springframework.boot:spring-boot-starter-web")
}
```

You can register these plugins for the components in Arciphant and they will be applied to every component project
created from the template — the architecture-specific Gradle setup is written once per component _type_, not once per
component:

```kotlin settings.gradle.kts
template()
    .createComponent(name = "web", plugin = "spring-web-component")
    .createComponent(name = "db", plugin = "jooq-component")
```

For complete, working convention plugins (Spring, jOOQ, MinIO, a Spring Boot bundle) see the
<a href="https://github.com/ergon/arciphant/tree/main/arciphant-project-demo/build-logic" target="_blank" rel="noreferrer">`build-logic`
of the demo project</a>.

## Bundle plugins

A plugin can also be registered for a [bundle module](/declare-structure#bundle-modules). This is the natural place for
packaging concerns — e.g. a convention plugin that applies Spring Boot and configures the executable jar:

```kotlin settings.gradle.kts
bundle(name = "online-learning-platform", plugin = "spring-boot-bundle-module")
```

## Use `includeBuild` instead of `buildSrc`

It is good practice to use a dedicated project for convention plugins instead of the `buildSrc` folder and to include
it with `includeBuild`:

1. **Create the build-logic project**

    Move the convention plugins into a separate Gradle build, e.g. `build-logic/src/main/kotlin/spring-web-component.gradle.kts`,
    with the `kotlin-dsl` plugin applied in its `build.gradle.kts`. Plugins that the convention plugins apply (e.g.
    `kotlin("jvm")`) must be on its classpath:

    ```kotlin build-logic/build.gradle.kts
    plugins {
        `kotlin-dsl`
    }

    repositories {
        gradlePluginPortal()
    }

    dependencies {
        // required since the convention plugins apply the Kotlin JVM plugin
        implementation("org.jetbrains.kotlin:kotlin-gradle-plugin:2.2.0")
    }
    ```

2. **Include it in the plugin management**

    ```kotlin settings.gradle.kts {3}
    pluginManagement {
      // …
      includeBuild("./build-logic")
    }
    ```

3. **Reference one plugin with apply false**

    Reference **one** of the convention plugins in the `plugins` block of your `settings.gradle.kts` with `apply false`:

    ```kotlin settings.gradle.kts {3}
    plugins {
      // …
      id("my-plugin") apply false // makes Gradle resolve plugins from the included build; the plugin is not applied here
    }
    ```

    :::warning[Required for plugins applied by Arciphant]
    Gradle only resolves plugins from builds included via `pluginManagement` when at least one plugin is referenced in a
    `plugins` block. Arciphant applies the registered plugins programmatically (`pluginManager.apply("plugin-id")`), which
    bypasses that resolution — so without this line, Gradle fails with `Plugin [id: '…'] was not found`. See also
    [Troubleshooting](/troubleshooting#convention-plugin-not-found).
    :::

    Referencing a single plugin is enough: it triggers Gradle's plugin resolution for the included build, and Arciphant can
    then apply _all_ plugins it provides.

4. **Register the plugins in the DSL**

    Register the convention plugins for the components and bundles as described [above](#component-plugins):

    ```kotlin settings.gradle.kts
    template()
        .createComponent(name = "web", plugin = "spring-web-component")
    ```