Creating a Custom Spring Boot Starter: Overview, Auto‑Configuration, and Usage

Spring Boot provides many starter modules for popular open‑source projects, but developers can also create their own custom starters to encapsulate internal libraries and simplify configuration within the Spring Boot context.

1. Overview

Custom starters avoid repetitive setup and enable rapid development; this article uncovers Spring Boot's inner workings and shows how to create a starter for a personal greeting library.

2. Unveiling Spring Boot Auto‑Configuration

2.1 Auto‑Configuration Classes

Since version 2.7, Spring Boot scans

META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports

for fully‑qualified auto‑configuration class names, such as

org.springframework.boot.autoconfigure.mongo.MongoAutoConfiguration

. Earlier versions use META-INF/spring.factories.

org.springframework.boot.autoconfigure.admin.SpringApplicationAdminJmxAutoConfiguration
org.springframework.boot.autoconfigure.amqp.RabbitAutoConfiguration
org.springframework.boot.autoconfigure.data.cassandra.CassandraDataAutoConfiguration
org.springframework.boot.autoconfigure.data.mongo.MongoDataAutoConfiguration
org.springframework.boot.autoconfigure.orm.jpa.HibernateJpaAutoConfiguration

Conditional initialization relies on @ConditionalOnClass; for example, MongoAutoConfiguration runs only if MongoClient is present on the classpath.

@Configuration
@ConditionalOnClass(MongoClient.class)
@EnableConfigurationProperties(MongoProperties.class)
@ConditionalOnMissingBean(type = "org.springframework.data.mongodb.MongoDbFactory")
public class MongoAutoConfiguration {
    // configuration code
}

2.2 Loading Custom Properties from application.properties

Properties prefixed with the class name (e.g., spring.data.mongodb) are bound to @ConfigurationProperties classes like MongoProperties.

@ConfigurationProperties(prefix = "spring.data.mongodb")
public class MongoProperties {
    private String host;
    // getters and setters
}

Setting spring.data.mongodb.host = localhost in application.properties configures the MongoDB host.

3. Building a Custom Starter

To create a starter, we need an auto‑configuration class, a properties class, a starter pom, and registration files.

3.1 Auto‑Configuration Module

The auto‑configuration module greeter-spring-boot-autoconfigure defines GreeterProperties and GreeterAutoConfiguration.

@ConfigurationProperties(prefix = "baeldung.greeter")
public class GreeterProperties {
    private String userName;
    private String morningMessage;
    private String afternoonMessage;
    private String eveningMessage;
    private String nightMessage;
    // getters and setters
}

@Configuration
@ConditionalOnClass(Greeter.class)
@EnableConfigurationProperties(GreeterProperties.class)
public class GreeterAutoConfiguration {

    @Autowired
    private GreeterProperties greeterProperties;

    @Bean
    @ConditionalOnMissingBean
    public GreetingConfig greeterConfig() {
        String userName = greeterProperties.getUserName() == null
            ? System.getProperty("user.name")
            : greeterProperties.getUserName();
        GreetingConfig greetingConfig = new GreetingConfig();
        greetingConfig.put(USER_NAME, userName);
        return greetingConfig;
    }

    @Bean
    @ConditionalOnMissingBean
    public Greeter greeter(GreetingConfig greetingConfig) {
        return new Greeter(greetingConfig);
    }
}

The fully‑qualified name com.baeldung.greeter.autoconfigure.GreeterAutoConfiguration is added to

META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports

(or spring.factories for pre‑2.7 versions).

3.2 Creating pom.xml for the Starter

<project ...>
    <modelVersion>4.0.0</modelVersion>
    <groupId>com.baeldung</groupId>
    <artifactId>greeter-spring-boot-starter</artifactId>
    <version>0.0.1-SNAPSHOT</version>
    <dependencies>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter</artifactId>
            <version>${spring-boot.version}</version>
        </dependency>
        <dependency>
            <groupId>com.baeldung</groupId>
            <artifactId>greeter-spring-boot-autoconfigure</artifactId>
            <version>${project.version}</version>
        </dependency>
        <dependency>
            <groupId>com.baeldung</groupId>
            <artifactId>greeter</artifactId>
            <version>${greeter.version}</version>
        </dependency>
    </dependencies>
    <properties>
        <greeter.version>0.0.1-SNAPSHOT</greeter.version>
    </properties>
</project>

3.3 Using the Starter

In a sample application, add the starter as a dependency:

<dependency>
    <groupId>com.baeldung</groupId>
    <artifactId>greeter-spring-boot-starter</artifactId>
    <version>${greeter-starter.version}</version>
</dependency>

Define custom properties in application.properties:

baeldung.greeter.userName=Baeldung
baeldung.greeter.afternoonMessage=Woha\ Afternoon

Inject and use the Greeter bean:

@SpringBootApplication
public class GreeterSampleApplication implements CommandLineRunner {

    @Autowired
    private Greeter greeter;

    public static void main(String[] args) {
        SpringApplication.run(GreeterSampleApplication.class, args);
    }

    @Override
    public void run(String... args) throws Exception {
        String message = greeter.greet();
        System.out.println(message);
    }
}

4. Conclusion

The guide demonstrates how to publish a custom Spring Boot starter and how its auto‑configuration simplifies configuration, reducing manual setup for developers.