Create a Custom Spring Boot Starter | Step-by-Step Guide

🚀 Introduction to Spring Boot Starters

Spring Boot Starters are dependency bundles that help developers quickly add functionality to their projects without manual configurations.

Example:
✔ spring-boot-starter-web – Adds dependencies for building web applications.
✔ spring-boot-starter-data-jpa – Configures JPA and Hibernate automatically.

🔹 Why Create a Custom Spring Boot Starter?
✅ Modularity – Encapsulates reusable functionality into a single dependency.
✅ Scalability – Helps in large projects and microservices architectures.
✅ Simplifies Development – Reduces boilerplate code in multiple projects.

📌 In this guide, you’ll learn:
✅ How to create a custom Spring Boot Starter from scratch.
✅ How to implement Auto Configuration using spring.factories.
✅ How to register beans conditionally for better flexibility.

1️⃣ Step 1: Create a New Maven Project for the Custom Starter

First, create a new Maven project that will act as the custom Spring Boot Starter.

📌 Create a New Project Structure

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

🚀 This structure ensures the starter can be used as a dependency in other projects.

2️⃣ Step 2: Define the CustomService Class

This is the core functionality provided by our starter.

📌 Create CustomService.java

package com.example.customstarter.config;

public class CustomService {
    
    private final String message;

    public CustomService(String message) {
        this.message = message;
    }

    public String printMessage() {
        return "Custom Starter Message: " + message;
    }
}

✅ This service will be automatically available when the starter is added to a project.

3️⃣ Step 3: Implement Auto Configuration

We will use Spring Boot Auto Configuration to register the CustomService bean when the starter is added as a dependency.

📌 Create CustomAutoConfiguration.java

package com.example.customstarter.config;

import org.springframework.boot.autoconfigure.condition.ConditionalOnMissingBean;
import org.springframework.boot.context.properties.ConfigurationProperties;
import org.springframework.boot.context.properties.EnableConfigurationProperties;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
@EnableConfigurationProperties(CustomProperties.class)
public class CustomAutoConfiguration {

    @Bean
    @ConditionalOnMissingBean
    public CustomService customService(CustomProperties properties) {
        return new CustomService(properties.getMessage());
    }
}

✅ This configuration:
✔ Loads CustomService as a Spring Bean.
✔ Uses @ConditionalOnMissingBean so users can override it if needed.
✔ Uses CustomProperties to allow external configuration.

4️⃣ Step 4: Create a Configuration Properties Class

Spring Boot allows users to configure the starter using application.properties.

📌 Create CustomProperties.java

package com.example.customstarter.config;

import org.springframework.boot.context.properties.ConfigurationProperties;

@ConfigurationProperties(prefix = "custom")
public class CustomProperties {
    
    private String message = "Hello from Custom Starter!"; // Default message

    public String getMessage() {
        return message;
    }

    public void setMessage(String message) {
        this.message = message;
    }
}

✅ Now users can configure the custom starter in application.properties:

custom.message=Welcome to My Custom Starter!

5️⃣ Step 5: Register Auto Configuration in spring.factories

Spring Boot loads auto-configuration classes from META-INF/spring.factories.

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

org.springframework.boot.autoconfigure.EnableAutoConfiguration=\
com.example.customstarter.config.CustomAutoConfiguration

✅ Spring Boot will automatically detect and load CustomAutoConfiguration.

6️⃣ Step 6: Package the Starter as a JAR

Modify pom.xml to make it a reusable Spring Boot Starter.

📌 Update pom.xml

<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>

    <name>Custom Spring Boot Starter</name>

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

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

✅ Run the following command to build the JAR file:

mvn clean install

🚀 Now the starter is ready to be used in any Spring Boot project!

7️⃣ Step 7: Use the Custom Starter in Another Project

To test the custom starter, create a new Spring Boot project and add the dependency.

📌 Add Dependency in pom.xml of a New Project

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

📌 Use CustomService in a Controller

@RestController
@RequestMapping("/api")
public class TestController {

    private final CustomService customService;

    public TestController(CustomService customService) {
        this.customService = customService;
    }

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

✅ Run the project and test the API in Postman:

GET http://localhost:8080/api/message

💡 Output:

Custom Starter Message: Welcome to My Custom Starter!

🎯 Summary: What We Learned

✅ Created a custom Spring Boot Starter project.
✅ Used @EnableAutoConfiguration for automatic configuration.
✅ Registered CustomService as a bean using spring.factories.
✅ Allowed external configuration with @ConfigurationProperties.
✅ Packaged and used the starter in another project.

🚀 Now you can create custom Spring Boot Starters to simplify development in multiple projects!

📢 Share this guide to help others build their own Spring Boot Starters! 🚀