Custom auto-configuration in Spring Boot

Introduction

Custom auto-configuration helps your Spring Boot app set up beans automatically without manual setup. It saves time and keeps your code clean.

You want to provide reusable setup for your own library or module.

You want to add default beans that users can override easily.

You want to simplify configuration for common use cases.

You want to conditionally create beans based on classpath or properties.

You want to share configuration across multiple projects.

Syntax

Spring Boot

@Configuration
@ConditionalOnClass(SomeClass.class)
@ConditionalOnProperty(prefix = "my.feature", name = "enabled", havingValue = "true", matchIfMissing = true)
public class MyAutoConfiguration {

    @Bean
    public MyService myService() {
        return new MyService();
    }
}

@Configuration marks the class as a source of bean definitions.

@ConditionalOnClass creates beans only if a class is on the classpath.

Examples

This auto-configuration creates a DataSource bean only if the DataSource class is available.

Spring Boot

@Configuration
@ConditionalOnClass(DataSource.class)
public class DataSourceAutoConfiguration {

    @Bean
    public DataSource dataSource() {
        return new HikariDataSource();
    }
}

This bean is created only if the property feature.enabled=true is set.

Spring Boot

@Configuration
@ConditionalOnProperty(prefix = "feature", name = "enabled", havingValue = "true")
public class FeatureAutoConfiguration {

    @Bean
    public FeatureService featureService() {
        return new FeatureService();
    }
}

This creates a MyService bean only if no other MyService bean is defined.

Spring Boot

@Configuration
@ConditionalOnMissingBean(MyService.class)
public class MyServiceAutoConfiguration {

    @Bean
    public MyService myService() {
        return new MyService();
    }
}

Sample Program

This example shows a custom auto-configuration class that creates a MyService bean if the class is present and a property myapp.service.enabled is true or missing. The main app fetches the bean and prints a greeting.

Spring Boot

package com.example.autoconfig;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.boot.autoconfigure.condition.ConditionalOnClass;
import org.springframework.boot.autoconfigure.condition.ConditionalOnProperty;
import org.springframework.boot.autoconfigure.condition.ConditionalOnMissingBean;

@Configuration
@ConditionalOnClass(MyService.class)
@ConditionalOnProperty(prefix = "myapp.service", name = "enabled", havingValue = "true", matchIfMissing = true)
public class MyServiceAutoConfiguration {

    @Bean
    @ConditionalOnMissingBean
    public MyService myService() {
        return new MyService();
    }
}

// Simple service class
class MyService {
    public String greet() {
        return "Hello from MyService!";
    }
}

// Main application to test auto-configuration
package com.example.demo;

import com.example.autoconfig.MyService;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.context.ApplicationContext;

@SpringBootApplication
public class DemoApplication {
    public static void main(String[] args) {
        ApplicationContext ctx = SpringApplication.run(DemoApplication.class, args);
        MyService service = ctx.getBean(MyService.class);
        System.out.println(service.greet());
    }
}

Important Notes

Always use @ConditionalOnMissingBean to allow users to override your beans.

Put your auto-configuration classes in spring.factories or use the new spring.autoconfigure file for Spring Boot 3+.

Test your auto-configuration by enabling/disabling properties and checking bean presence.

Summary

Custom auto-configuration creates beans automatically based on conditions.

Use conditions like class presence and properties to control bean creation.

It helps make reusable, easy-to-configure Spring Boot modules.