Creating a Custom Starter with Spring Boot

Spring Boot starters are a set of convenient dependency descriptors you can include in your application to enable specific features. Creating a custom Spring Boot starter allows you to bundle and distribute common configurations, dependencies, and auto-configurations to simplify the setup for multiple applications. This tutorial will guide you through the step-by-step process of creating a custom Spring Boot starter.

Prerequisites

• JDK 17 or later
• Maven or Gradle
• IDE (IntelliJ IDEA, Eclipse, etc.)

Step 1: Set Up the Custom Starter Project

1.1 Create a New Maven Project

You can create a new Maven project using your IDE or by using the Spring Initializr. For this example, we will set up the project manually.

1.1.1 Directory Structure

Create the following directory structure for your custom starter:

custom-spring-boot-starter
├── src
│   ├── main
│   │   ├── java
│   │   │   └── com
│   │   │       └── example
│   │   │           └── starter
│   │   │               ├── CustomAutoConfiguration.java
│   │   ├── resources
│   │       └── META-INF
│   │           └── spring.factories
├── pom.xml

1.2 Create pom.xml

Create the pom.xml file for your custom starter project.

<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>
    <groupId>com.example</groupId>
    <artifactId>custom-spring-boot-starter</artifactId>
    <version>1.0.0</version>
    <packaging>jar</packaging>

    <parent>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-parent</artifactId>
        <version>3.2.0</version>
    </parent>

    <dependencies>
        <!-- Spring Boot Auto-Configuration -->
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-autoconfigure</artifactId>
        </dependency>
        <!-- Spring Boot Starter -->
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter</artifactId>
        </dependency>
    </dependencies>

    <build>
        <plugins>
            <plugin>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-maven-plugin</artifactId>
            </plugin>
        </plugins>
    </build>
</project>

Explanation:

• The project inherits from spring-boot-starter-parent.
• It includes spring-boot-autoconfigure and spring-boot-starter dependencies.

Step 2: Create Auto-Configuration Class

2.1 Create CustomAutoConfiguration.java

Create the auto-configuration class for your starter.

package com.example.starter;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
public class CustomAutoConfiguration {

    @Bean
    public CustomService customService() {
        return new CustomService();
    }
}

2.2 Create CustomService.java

Create a simple service that will be auto-configured.

package com.example.starter;

public class CustomService {

    public String getMessage() {
        return "Hello from Custom Starter!";
    }
}

Step 3: Register the Auto-Configuration

3.1 Create spring.factories

Create the spring.factories file in src/main/resources/META-INF.

# src/main/resources/META-INF/spring.factories

org.springframework.boot.autoconfigure.EnableAutoConfiguration=\
com.example.starter.CustomAutoConfiguration

Explanation:

• This file registers the auto-configuration class so Spring Boot can discover and apply it.

Step 4: Publish the Custom Starter to a Local Repository

4.1 Build and Install the Starter

Run the following Maven command to build and install the custom starter to your local Maven repository.

./mvnw clean install

Explanation:

• This command compiles the code, runs tests, and installs the JAR file in the local Maven repository.

Step 5: Use the Custom Starter in a Spring Boot Application

5.1 Create a New Spring Boot Application

Use Spring Initializr to create a new Spring Boot application with the following dependencies:

• Spring Web

Download and unzip the project, then open it in your IDE.

5.2 Add the Custom Starter Dependency

Add the custom starter dependency to the pom.xml file of your Spring Boot application.

<dependency>
    <groupId>com.example</groupId>
    <artifactId>custom-spring-boot-starter</artifactId>
    <version>1.0.0</version>
</dependency>

5.3 Create a REST Controller

Create a REST controller to use the CustomService.

package com.example.demo;

import com.example.starter.CustomService;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
public class HelloController {

    @Autowired
    private CustomService customService;

    @GetMapping("/hello")
    public String hello() {
        return customService.getMessage();
    }
}

Explanation:

• CustomService is auto-configured and injected into the HelloController via dependency injection.
• The /hello endpoint returns a message from CustomService.

Step 6: Run and Test the Application

6.1 Run the Application

Run the Spring Boot application using your IDE or the command line:

./mvnw spring-boot:run

6.2 Test the Endpoint

Open your browser and navigate to http://localhost:8080/hello. You should see the following response:

Hello from Custom Starter!

Conclusion

In this tutorial, you have learned how to create a custom Spring Boot starter. By following these steps, you can bundle common configurations, dependencies, and auto-configurations into a reusable starter. This approach simplifies the setup for multiple applications and promotes consistency across projects.