Skip to main content
PreparationZone Logo
PrepZone

How Auto-Configuration Works

Conditional beans, AutoConfiguration.imports, and how Boot configures itself.

Pass checkpoint below

Why this matters

  • Understanding auto-config explains why adding a starter suddenly gives you a DataSource, Jackson, or SecurityFilterChain without writing config.
  • Debugging "bean not found" or "bean already defined" conflicts requires knowing which auto-config class created the bean.
  • Writing custom starters for shared BookStore libraries depends on the same conditional mechanism.

Conditional beans

L1 · Fresher

Auto-config classes register beans only when classpath and properties match — e.g. DataSource when JDBC is present and spring.datasource.url is set.

AutoConfiguration.imports (Boot 3)

L2 · Intermediate

Boot 3 lists auto-config class names in AutoConfiguration.imports instead of spring.factories for faster startup and clearer ownership.

@ConditionalOnMissingBean

L3 · Advanced

Your custom ObjectMapper or DataSource replaces Boot's default because auto-config backs off when a bean type already exists.

Ordering with @AutoConfigureBefore

L4 · Expert

Custom security or Jackson config may need to run before or after specific auto-config classes. Use @AutoConfigureBefore / @After to avoid subtle ordering bugs.

How auto-config loads

Boot 3.x reads candidate classes from:

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

Each line is a fully qualified @Configuration class. AutoConfigurationImportSelector loads them after your own @Configuration classes, so your beans take precedence.

Example entry for the web starter:

Java
org.springframework.boot.autoconfigure.web.servlet.DispatcherServletAutoConfiguration
org.springframework.boot.autoconfigure.jackson.JacksonAutoConfiguration

Conditional evaluation

Every auto-config class uses @Conditional annotations:

Java
// learn:fragment
@AutoConfiguration
@ConditionalOnClass(DataSource.class)
@ConditionalOnProperty(name = "spring.datasource.url")
@EnableConfigurationProperties(DataSourceProperties.class)
public class DataSourceAutoConfiguration {
    @Bean
    @ConditionalOnMissingBean
    public DataSource dataSource(DataSourceProperties props) {
        return DataSourceBuilder.create()
            .url(props.getUrl())
            .username(props.getUsername())
            .password(props.getPassword())
            .build();
    }
}

Beans register only when:

DataSource auto-config conditions

  • DataSource class is on the classpath (JPA starter present)
  • spring.datasource.url property is set
  • No user-defined DataSource @Bean already exists
Classpath scanFind @AutoConfiguration classes
@Conditional checksOnClass, OnBean, OnProperty
Register beansOnly if conditions pass
Boot checks classpath and existing beans before creating defaults.

Common @ConditionalOn* annotations

  • @ConditionalOnClass — Classpath contains the named class.
  • @ConditionalOnMissingBean — No bean of this type registered yet (user override wins).
  • @ConditionalOnProperty — Property matches expected value.
  • @ConditionalOnWebApplication — Running as a servlet web app.
  • @ConditionalOnExpression — SpEL expression evaluates to true.

The rest of this guide is part of Pro

Free covers every fresher guide in full. Pro unlocks Senior, Staff and Architect guides across every track.

Still to come · 5 sections

  • User overrides auto-config
  • Inspecting what matched
  • Auto-config ordering
  • Disabling auto-config
  • The @AutoConfiguration annotation

Test yourself

Answer these before moving on — recall is what makes it stick.