Customizing a Spring Boot Starter and Controlling Auto‑Configuration Execution Order

In everyday development the starters provided by Spring Boot are often sufficient, but when integrating an unfamiliar component you may need to create a custom starter to achieve a plug‑and‑play experience.

The article builds on a previous deep dive into Spring Boot’s auto‑configuration mechanism and shows how to both create a starter and analyse the ordering of its auto‑configuration classes.

The core of a starter is an auto‑configuration class, which is loaded by AutoConfigurationImportSelector from the spring.factories file. Therefore you only need to place your custom auto‑configuration class in that file.

Common annotations used in auto‑configuration classes include:

@Configuration : marks the class as a configuration class (optional for auto‑configuration).

@EnableConfigurationProperties : binds external properties to a POJO.

@ConditionalOn… : conditional execution based on environment or classpath.

@AutoConfigureAfter , @AutoConfigureBefore , @AutoConfigureOrder : control the relative execution order.

Step 1: Prepare your own auto‑configuration class

@Configuration
@AutoConfigureAfter(DataSourceAutoConfiguration.class)
@AutoConfigureOrder(Ordered.HIGHEST_PRECEDENCE + 5)
@ConditionalOnProperty(prefix = "my.auto", name = "enabled", havingValue = "true", matchIfMissing = true)
public class MyCustomAutoConfiguration {
    // custom beans and settings
}

Step 2: Register the class in spring.factories

# Auto Configure
org.springframework.boot.autoconfigure.EnableAutoConfiguration=\
com.example.autoconfig.MyCustomAutoConfiguration

After packaging the starter, adding it as a Maven dependency makes it work automatically.

How to specify the execution order of auto‑configuration classes

Use the three annotations mentioned earlier:

@AutoConfigureAfter : run after the specified class.

@AutoConfigureBefore : run before the specified class.

@AutoConfigureOrder : lower numeric value means higher priority.

Classic mistake

Applying @AutoConfigureAfter or @AutoConfigureBefore on a regular @Configuration class has no effect; these annotations only work on true auto‑configuration classes.

Source‑code analysis of how auto‑configuration classes are sorted

return sortAutoConfigurations(processedConfigurations, getAutoConfigurationMetadata())
    .stream()
    .map(importClassName -> new Entry(this.entries.get(importClassName), importClassName))
    .collect(Collectors.toList());

The sorting logic in AutoConfigurationSorter.getInPriorityOrder() follows three steps:

Alphabetical order.

Order by @AutoConfigureOrder (lower value first).

Finally apply @AutoConfigureAfter and @AutoConfigureBefore relationships.

Thus the final order is primarily determined by the @AutoConfigureAfter and @AutoConfigureBefore annotations.

Conclusion

The article demonstrates how to build a custom Spring Boot starter and precisely control the execution order of its auto‑configuration classes, enabling developers to integrate new components seamlessly and predictably.