Creating Custom Spring Boot Starters: Auto-Configuration and Conditionals

Spring Boot starters are the backbone of modern microservice architectures. They let you add complex functionality — from database access to messaging to security — with a single dependency in your pom.xml. But what if the starter you need doesn't exist? Or what if your organization has internal libraries that should be auto-configured? That's when you build your own. Creating a custom Spring Boot starter is a rite of passage for senior developers. It forces you to understand auto-configuration mechanics, conditional annotations, and the delicate dance between convention and configuration. In this tutorial, we'll build a production-ready starter for a SaaS billing service. You'll learn how to register auto-configuration classes, apply conditionals that respect the user's environment, and test everything like a pro. We'll also cover the pitfalls — like classpath scanning order and property binding quirks — that have caused midnight PagerDuty alerts for many of us. By the end, you'll have a reusable starter that can be dropped into any Spring Boot 3.2+ project and just work. Let's get our hands dirty.

What is a Spring Boot Starter?

A Spring Boot starter is a Maven or Gradle module that bundles together all the dependencies and auto-configuration needed to enable a feature. When you add spring-boot-starter-web to your project, you get Tomcat, Jackson, Spring MVC, and a pile of auto-configured beans. The magic happens because Spring Boot scans for META-INF/spring.factories (or the newer org.springframework.boot.autoconfigure.AutoConfiguration.imports file) to discover auto-configuration classes. These classes use conditional annotations to decide what to configure based on the classpath, properties, and existing beans. For example, spring-boot-starter-data-redis only creates a RedisConnectionFactory if you have the Lettuce or Jedis driver on the classpath. This design means starters are additive: you can stack them without conflicts. But when you build your own, you must follow the same contract. Let's build a starter for a fictional billing service called "ChargeBee Lite" that provides a PaymentGateway interface and a default implementation using Stripe.

package com.example.billing.starter;

import org.springframework.boot.autoconfigure.AutoConfiguration;
import org.springframework.boot.autoconfigure.condition.ConditionalOnClass;
import org.springframework.boot.autoconfigure.condition.ConditionalOnMissingBean;
import org.springframework.boot.context.properties.EnableConfigurationProperties;
import org.springframework.context.annotation.Bean;

@AutoConfiguration
@ConditionalOnClass(StripeClient.class)
@EnableConfigurationProperties(BillingProperties.class)
public class BillingAutoConfiguration {

    @Bean
    @ConditionalOnMissingBean
    public PaymentGateway paymentGateway(BillingProperties props) {
        return new StripePaymentGateway(props.getApiKey());
    }
}

What the Official Docs Won't Tell You

The official Spring Boot documentation tells you to use @ConditionalOnClass and spring.factories. It doesn't tell you about the silent failures when your starter's auto-configuration class is loaded but the conditionals fail silently. I've spent hours debugging a starter that worked in unit tests but not in production — the culprit was a missing transitive dependency that the conditionals didn't detect because they only check class presence, not method availability. Another hidden gotcha: property binding with @ConfigurationProperties. If your starter defines properties in a prefix like "billing.api-key", the user must use kebab-case in application.yml. But if they use camelCase (billing.apiKey), it still works — until they upgrade Spring Boot and the relaxed binding rules change. The docs also gloss over ordering. If two starters both try to configure a DataSource, the one with @AutoConfigureBefore wins. Without explicit ordering, the result is unpredictable. Finally, never rely on @ComponentScan in your starter — it defeats the purpose of auto-configuration and can cause bean duplication. Always use explicit @Bean methods with conditionals.

package com.example.billing.starter;

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

@ConfigurationProperties(prefix = "billing")
public class BillingProperties {

    private String apiKey;
    private String webhookSecret;
    private boolean enabled = true;

    public String getApiKey() { return apiKey; }
    public void setApiKey(String apiKey) { this.apiKey = apiKey; }
    public String getWebhookSecret() { return webhookSecret; }
    public void setWebhookSecret(String webhookSecret) { this.webhookSecret = webhookSecret; }
    public boolean isEnabled() { return enabled; }
    public void setEnabled(boolean enabled) { this.enabled = enabled; }
}

Registering Auto-Configuration

Spring Boot discovers auto-configuration classes via the file META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports. This file (introduced in Spring Boot 2.7) replaces the older spring.factories approach. Each line contains the fully qualified name of an auto-configuration class. For backward compatibility, you can still use spring.factories, but the new method is preferred. Create the file in src/main/resources/META-INF/spring/. The order of classes in this file matters: Spring Boot processes them in order, but you can override ordering with @AutoConfigureBefore and @AutoConfigureAfter annotations. For our billing starter, we'll register BillingAutoConfiguration. If your starter depends on another auto-configuration (like DataSourceAutoConfiguration), list it after in the imports file or use @AutoConfigureAfter. A common mistake is forgetting to include this file — the starter will compile but do nothing at runtime. I've seen teams waste days wondering why their beans aren't created, only to find the imports file missing.

com.example.billing.starter.BillingAutoConfiguration
com.example.billing.starter.BillingWebhookAutoConfiguration

Conditional Annotations Deep Dive

Spring Boot provides a rich set of conditional annotations that control whether a bean or configuration class is loaded. The most common ones are @ConditionalOnClass (checks if a class is on the classpath), @ConditionalOnMissingBean (checks if a bean of a given type doesn't exist), @ConditionalOnProperty (checks if a property has a specific value), and @ConditionalOnExpression (evaluates a SpEL expression). You can combine them on the same class or method. For our billing starter, we want to enable the Stripe integration only if the Stripe SDK is present and the property 'billing.enabled' is true (default true). We also want to allow users to provide their own PaymentGateway implementation. The order of evaluation matters: @ConditionalOnClass is checked first, then @ConditionalOnProperty, then @ConditionalOnMissingBean. If any condition fails, the entire configuration class is skipped. This is important for performance — you don't want to load beans if the required library isn't even on the classpath. A common mistake is putting @ConditionalOnMissingBean on the class level instead of the method level. If you do that, the entire configuration class is skipped if the bean exists, which prevents other beans in the same class from being created.

package com.example.billing.starter;

import org.springframework.boot.autoconfigure.AutoConfiguration;
import org.springframework.boot.autoconfigure.condition.ConditionalOnClass;
import org.springframework.boot.autoconfigure.condition.ConditionalOnMissingBean;
import org.springframework.boot.autoconfigure.condition.ConditionalOnProperty;
import org.springframework.boot.context.properties.EnableConfigurationProperties;
import org.springframework.context.annotation.Bean;

@AutoConfiguration
@ConditionalOnClass(name = "com.stripe.Stripe")
@ConditionalOnProperty(prefix = "billing", name = "enabled", havingValue = "true", matchIfMissing = true)
@EnableConfigurationProperties(BillingProperties.class)
public class ConditionalBillingAutoConfiguration {

    @Bean
    @ConditionalOnMissingBean
    public PaymentGateway paymentGateway(BillingProperties props) {
        return new StripePaymentGateway(props.getApiKey());
    }

    @Bean
    @ConditionalOnMissingBean
    public WebhookHandler webhookHandler(BillingProperties props) {
        return new StripeWebhookHandler(props.getWebhookSecret());
    }
}

Structuring Your Starter Project

A well-structured starter project has two modules: the autoconfigure module and the starter module. The autoconfigure module contains the auto-configuration classes, property classes, and conditionals. The starter module is an empty JAR that pulls in the autoconfigure module and the required third-party dependencies. This separation allows users to depend on the autoconfigure module directly if they want to customize the configuration. For our billing starter, the autoconfigure module includes BillingAutoConfiguration, BillingProperties, and the StripePaymentGateway implementation. The starter module depends on the autoconfigure module and the Stripe SDK. The user only needs to add the starter module to their project. This pattern is used by all official Spring Boot starters. Another best practice: keep your API interfaces (like PaymentGateway) in a separate API module that has no Spring dependencies. This allows users to implement the interface without pulling in Spring Boot. I've seen projects where the API interface was in the autoconfigure module, forcing users to depend on Spring Boot just to implement a simple interface. Don't do that.

<project>
    <modelVersion>4.0.0</modelVersion>
    <groupId>com.example.billing</groupId>
    <artifactId>billing-spring-boot-starter</artifactId>
    <version>1.0.0</version>
    <dependencies>
        <dependency>
            <groupId>com.example.billing</groupId>
            <artifactId>billing-spring-boot-autoconfigure</artifactId>
            <version>1.0.0</version>
        </dependency>
        <dependency>
            <groupId>com.stripe</groupId>
            <artifactId>stripe-java</artifactId>
            <version>24.0.0</version>
        </dependency>
    </dependencies>
</project>

Testing Your Custom Starter

Testing a custom starter requires a different approach than testing a regular application. You need to verify that the auto-configuration activates under the right conditions and deactivates under others. Use @SpringBootTest with a minimal application context. For our billing starter, we'll write tests that verify: 1) When Stripe SDK is on the classpath and billing.enabled is true, the PaymentGateway bean is created. 2) When Stripe SDK is missing, the bean is not created. 3) When the user provides their own PaymentGateway bean, the starter's bean is not created. To simulate missing classes, use a custom TestCondition or exclude the Stripe dependency from the test classpath. Spring Boot 3.2 introduced @ConditionalOnClass with a name attribute that accepts string class names, making it easier to test without the actual library. For property-based tests, use @TestPropertySource or @DynamicPropertySource. A common mistake is testing only the happy path and assuming conditionals work. Always test the negative cases: missing properties, missing classes, and existing beans.

import org.junit.jupiter.api.Test;
import org.springframework.boot.autoconfigure.AutoConfigurations;
import org.springframework.boot.test.context.runner.ApplicationContextRunner;

import static org.assertj.core.api.Assertions.assertThat;

class BillingAutoConfigurationTest {

    private final ApplicationContextRunner runner = new ApplicationContextRunner()
            .withConfiguration(AutoConfigurations.of(BillingAutoConfiguration.class));

    @Test
    void shouldCreatePaymentGatewayWhenStripePresent() {
        runner.withPropertyValues("billing.api-key=test_key")
              .run(context -> {
                  assertThat(context).hasSingleBean(PaymentGateway.class);
              });
    }

    @Test
    void shouldNotCreatePaymentGatewayWhenDisabled() {
        runner.withPropertyValues("billing.enabled=false")
              .run(context -> {
                  assertThat(context).doesNotHaveBean(PaymentGateway.class);
              });
    }

    @Test
    void shouldRespectUserDefinedBean() {
        runner.withBean(CustomPaymentGateway.class)
              .run(context -> {
                  assertThat(context).hasSingleBean(PaymentGateway.class);
                  assertThat(context).getBean(PaymentGateway.class)
                          .isInstanceOf(CustomPaymentGateway.class);
              });
    }
}

Production Debugging and Monitoring

When a custom starter misbehaves in production, the first step is to determine whether the auto-configuration was applied. Enable debug logging for your starter's package by adding 'logging.level.com.example.billing.starter=DEBUG' to application.yml. This will show you which conditionals matched and which didn't. Spring Boot also exposes an autoconfigure endpoint via Actuator: GET /actuator/conditions. This endpoint shows all auto-configuration classes and their match/unmatch status. If your starter's class is listed as unmatched, the 'not matched' section will tell you why — for example, 'ConditionalOnClass did not find required class com.stripe.Stripe'. This is invaluable for debugging. Another technique: use Spring Boot's --debug flag to print the autoconfigure report at startup. I once debugged a production issue where the starter's bean was created twice — the autoconfigure report showed two matching entries because the user had accidentally included both the starter and the autoconfigure module as dependencies. The report made it obvious.

logging:
  level:
    com.example.billing.starter: DEBUG

management:
  endpoints:
    web:
      exposure:
        include: conditions

Advanced Techniques: Conditional Evaluation Order

When you have multiple auto-configuration classes in your starter, the order of evaluation matters. Use @AutoConfigureBefore and @AutoConfigureAfter to specify ordering. For example, if your billing starter needs a DataSource to store transactions, you should annotate your configuration with @AutoConfigureAfter(DataSourceAutoConfiguration.class). This ensures the DataSource is available when your beans are created. Another advanced technique is using @ConditionalOnBean with a specific bean name or type. This is useful when your starter should only activate if another starter's bean is present. For example, your billing starter might only create a webhook endpoint if Spring Security is configured. Use @ConditionalOnBean(SecurityFilterChain.class) on the webhook configuration. Be careful with circular dependencies — if two starters depend on each other's beans, you'll get a startup failure. Finally, you can create custom conditionals by implementing the Condition interface. This is useful for complex logic that can't be expressed with the built-in annotations. For example, a condition that checks the environment (dev vs prod) based on a custom property.

package com.example.billing.starter;

import org.springframework.context.annotation.Condition;
import org.springframework.context.annotation.ConditionContext;
import org.springframework.core.type.AnnotatedTypeMetadata;

public class OnProductionEnvironmentCondition implements Condition {

    @Override
    public boolean matches(ConditionContext context, AnnotatedTypeMetadata metadata) {
        String env = context.getEnvironment().getProperty("billing.environment");
        return "production".equalsIgnoreCase(env);
    }
}