Write Your Own Spring Boot 4 Starter: Auto-Configuration, @Conditional and Properties

Versions. Spring Boot 4.1.1 and Spring Framework 7.0.9 (both poms were published to Maven Central on 20 August 2026), on Java 25 (LTS, Temurin 25.0.4.1) and Maven 3.9. Boot 4 split the old spring-boot-autoconfigure jar into per-technology modules, which changes what a starter imports; the section on Boot 4 has the measured details.

A starter is two jars and a text file

com.ankurm.masker.MaskerAutoConfiguration
com.ankurm.masker.MaskerJacksonAutoConfiguration

<dependencies>
  <dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter</artifactId>
  </dependency>
  <dependency>
    <groupId>com.ankurm.masker</groupId>
    <artifactId>masker-spring-boot-autoconfigure</artifactId>
    <version>${project.version}</version>
  </dependency>
</dependencies>

--- masker-spring-boot-starter-1.0.0.jar ---
META-INF/MANIFEST.MF
META-INF/maven/com.ankurm.masker/masker-spring-boot-starter/pom.xml
META-INF/maven/com.ankurm.masker/masker-spring-boot-starter/pom.properties

--- masker-spring-boot-autoconfigure-1.0.0.jar (META-INF and the classes) ---
META-INF/spring-autoconfigure-metadata.properties
META-INF/additional-spring-configuration-metadata.json
META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports
META-INF/spring-configuration-metadata.json
com/ankurm/masker/MaskerJacksonAutoConfiguration.class
com/ankurm/masker/Sensitive.class
com/ankurm/masker/Masker.class
com/ankurm/masker/MaskerAutoConfiguration.class
com/ankurm/masker/TailMasker.class
com/ankurm/masker/MaskerJacksonModule.class
com/ankurm/masker/MaskerProperties.class
com/ankurm/masker/MaskerJacksonModule$1.class

\- org.springframework.boot:spring-boot-starter-jackson:jar:4.1.1:compile (optional)

Going deeper

• Boot reference: naming your starter and its modules
• Boot reference: configuration keys and namespaces
• The three module poms: the parent, autoconfigure, starter

The smallest thing that works: one class, one record, one line in a text file

@AutoConfiguration
@ConditionalOnProperty(prefix = "masker", name = "enabled", matchIfMissing = true)
@EnableConfigurationProperties(MaskerProperties.class)
public class MaskerAutoConfiguration {

    /** Backs off when the application defines its own {@link Masker}. */
    @Bean
    @ConditionalOnMissingBean
    public Masker masker(MaskerProperties properties) {
        return new TailMasker(properties.replacement(), properties.visibleTail());
    }
}

/**
 * Settings for the auto-configured {@link Masker}.
 *
 * @param enabled     whether the starter configures anything at all
 * @param replacement the text that stands in for each hidden character
 * @param visibleTail how many characters at the end of the value stay readable
 */
@ConfigurationProperties("masker")
public record MaskerProperties(
        @DefaultValue("true") boolean enabled,
        @DefaultValue("*") String replacement,
        @DefaultValue("4") int visibleTail) {
}

@SpringBootApplication
public class DemoApplication {

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

Masker beans           : [masker]
MaskerProperties beans : [masker-com.ankurm.masker.MaskerProperties]
Jackson module beans   : [maskerJacksonModule]
JSON of a Customer     : {"name":"Asha","card":"************1111"}

org.springframework.context.annotation.Configuration(
proxyBeanMethods=false
org.springframework.boot.autoconfigure.AutoConfigureBefore
org.springframework.boot.autoconfigure.AutoConfigureAfter

Going deeper

• @ConfigurationProperties vs @Value in Spring Boot 4 for relaxed binding, records and validation of the properties record
• Dependency Injection in Spring Boot 4 for why the demo receives the bean without asking for it by name
• Boot reference: externalized configuration

Backing off: how a starter stays out of the way

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

/** A user configuration. Deliberately not annotated: the runner registers whatever class it is given. */
static class CustomMasker {
    @Bean
    Masker customMasker() {
        return value -> "<redacted>";
    }
}

--- user configuration + auto-configuration (the way Boot loads them) ---
Masker beans           : [customMasker]
getBean(Masker.class)  : mask -> <redacted>

--- --masker.enabled=false ---
Masker beans           : []
Jackson module beans   : []

--- what Boot recorded ---
com.ankurm.masker.MaskerAutoConfiguration  [not matched]
    did not match: @ConditionalOnProperty (masker.enabled) found different value in property 'enabled'
com.ankurm.masker.MaskerJacksonAutoConfiguration  [not matched]
    matched: @ConditionalOnClass found required class 'tools.jackson.databind.json.JsonMapper'
    did not match: @ConditionalOnBean (types: com.ankurm.masker.Masker; SearchStrategy: all) did not find any beans of type com.ankurm.masker.Masker

A property condition without matchIfMissing is off until somebody sets it. @ConditionalOnProperty on its own matches only when the property exists (and is not false). A starter written that way does nothing after the dependency is added, and the person who added it sees no error, only a missing bean. Boot’s report says it plainly, 16-conditional-on-property-without-match-if-missing.txt:

Marker beans : 0
com.ankurm.traps.DefaultOffAutoConfiguration  [not matched]
    did not match: @ConditionalOnProperty (traps.enabled) did not find property 'enabled'

Decide deliberately which way your default should point. For a starter whose whole purpose is to configure something, matchIfMissing = true is usually right. For one that costs something (a connection, a background thread), off by default is defensible, and the README should say so on the first line.

--- the same two classes registered as ordinary configuration, starter first ---
Masker beans           : [masker, customMasker]
getBean(Masker.class)  : NoUniqueBeanDefinitionException

--- the same two classes, user configuration first ---
Masker beans           : [customMasker]

Going deeper

• Boot reference: condition annotations
• How a hand-written configuration class fares in the same test: MaskerAutoConfigurationTests.java
• Why Your Spring Boot App Takes 8 Seconds to Start, for what a large number of auto-configurations costs at start-up

Properties, and the metadata that makes an editor understand them

<annotationProcessorPaths>
  <path>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-configuration-processor</artifactId>
  </path>
  <path>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-autoconfigure-processor</artifactId>
  </path>
</annotationProcessorPaths>

    {
      "name": "masker.visible-tail",
      "type": "java.lang.Integer",
      "description": "how many characters at the end of the value stay readable",
      "sourceType": "com.ankurm.masker.MaskerProperties",
      "defaultValue": 4
    }

{
  "hints": [
    {
      "name": "masker.replacement",
      "values": [
        { "value": "*", "description": "Asterisk (the default)." },
        { "value": "#", "description": "Hash sign." },
        { "value": "•", "description": "Bullet." }
      ]
    }
  ]
}

com.ankurm.masker.MaskerAutoConfiguration=
com.ankurm.masker.MaskerJacksonAutoConfiguration=
com.ankurm.masker.MaskerJacksonAutoConfiguration.AutoConfigureAfter=com.ankurm.masker.MaskerAutoConfiguration
com.ankurm.masker.MaskerJacksonAutoConfiguration.ConditionalOnBean=com.ankurm.masker.Masker
com.ankurm.masker.MaskerJacksonAutoConfiguration.ConditionalOnClass=tools.jackson.databind.json.JsonMapper

The version in annotationProcessorPaths is the one trap in this section. Maven needs a version for the processor. With the Spring Boot starter parent as your parent, leaving it out works: the build above resolved the processor at 4.1.1 from Boot’s dependency management. The same pom fails the moment you write ${project.parent.version}, the natural thing to type, if your module’s parent is your own multi-module parent and not Boot’s. Boot is then the grandparent, project.parent.version is the version of your parent, and Maven looks for a processor that does not exist. Reproduced by rewriting the pom in a scratch copy (15-annotation-processor-version-trap.txt):

Failed to execute goal org.apache.maven.plugins:maven-compiler-plugin:3.15.0:compile (default-compile) on project masker-spring-boot-autoconfigure: Resolution of annotationProcessorPath dependencies failed: The following artifacts could not be resolved: org.springframework.boot:spring-boot-configuration-processor:jar:1.0.0 (absent): Could not find artifact org.springframework.boot:spring-boot-configuration-processor:jar:1.0.0 in central (https://repo.maven.apache.org/maven2)

Leave the version out and let the Boot parent manage it, or use a property that is defined to the Boot version.

Going deeper

• Boot reference: generating your own metadata with the annotation processor
• Boot reference: configuration metadata format
• @ConfigurationProperties vs @Value in Spring Boot 4, which generates the same metadata for an application’s own properties

Optional integrations: @ConditionalOnClass, and where it is safe to put it

@AutoConfiguration(after = MaskerAutoConfiguration.class)
@ConditionalOnClass(JsonMapper.class)
@ConditionalOnBean(Masker.class)
public class MaskerJacksonAutoConfiguration {

    @Bean
    @ConditionalOnMissingBean
    public MaskerJacksonModule maskerJacksonModule(Masker masker) {
        return new MaskerJacksonModule(masker);
    }
}

com.ankurm.masker.MaskerJacksonAutoConfiguration  [matched]
    matched: @ConditionalOnClass found required class 'tools.jackson.databind.json.JsonMapper'
    matched: @ConditionalOnBean (types: com.ankurm.masker.Masker; SearchStrategy: all) found bean 'masker'
com.ankurm.masker.MaskerJacksonAutoConfiguration#maskerJacksonModule  [matched]
    matched: @ConditionalOnMissingBean (types: com.ankurm.masker.MaskerJacksonModule; SearchStrategy: all) did not find any beans

context failed     : false
Masker beans       : [masker]
module beans       : []

--- what Boot recorded for the Jackson auto-configuration ---
com.ankurm.masker.MaskerJacksonAutoConfiguration  [not matched]
    did not match: @ConditionalOnClass did not find required class 'tools.jackson.databind.json.JsonMapper'

@AutoConfiguration
public class MethodLevelConditionAutoConfiguration {

    @Bean
    @ConditionalOnClass(JsonMapper.class)
    MaskerJacksonModule methodLevelModule(Masker masker) {
        return new MaskerJacksonModule(masker);
    }
}

@AutoConfiguration
public class NestedConditionAutoConfiguration {

    @Configuration(proxyBeanMethods = false)
    @ConditionalOnClass(JsonMapper.class)
    static class JacksonConfiguration {

        @Bean
        MaskerJacksonModule nestedModule(Masker masker) {
            return new MaskerJacksonModule(masker);
        }
    }
}

--- condition on the @Bean method, classpath without any Jackson jar ---
context failed
exception chain: BeanDefinitionStoreException -> IllegalStateException -> NoClassDefFoundError -> ClassNotFoundException
root cause     : java.lang.ClassNotFoundException: tools.jackson.databind.module.SimpleModule

--- condition on a nested class, classpath without any Jackson jar ---
context started; nestedModule bean present: false

--- condition on the @Bean method, classpath with Jackson ---
context started; methodLevelModule bean present: true

This one cannot be caught by the obvious test. My first version of the check was an ApplicationContextRunner test with FilteredClassLoader("tools.jackson"), and it passed: the context started. The same class fails on a real classpath without Jackson, as above. My reading is that the class under test had already been loaded by the test’s own class loader, which can see Jackson, so the filter never got a chance to matter. I did not investigate further, and the takeaway does not depend on the cause: a green FilteredClassLoader test proves the condition works, not that the class loads without the library. If the starter has an optional dependency, run it once on a classpath that really lacks it. The demo application in this repository does not do that, because it brings Jackson itself.

Going deeper

• Boot reference: class conditions, including why @Bean methods need a separate configuration class
• The two demonstration classes and the launcher: the traps package (in the repository, under the test sources)

Order matters: a @ConditionalOnBean that is false because of a class name

@AutoConfiguration
@ConditionalOnBean(JsonMapper.class)
public class EarlyModuleAutoConfiguration {

    @Bean
    Marker earlyMarker() {
        return new Marker("EarlyModuleAutoConfiguration");
    }
}

@AutoConfiguration(afterName = "org.springframework.boot.jackson.autoconfigure.JacksonAutoConfiguration")
@ConditionalOnBean(JsonMapper.class)
public class OrderedModuleAutoConfiguration {

    @Bean
    Marker orderedMarker() {
        return new Marker("OrderedModuleAutoConfiguration");
    }
}

com.ankurm.masker.MaskerAutoConfiguration
com.ankurm.traps.EarlyModuleAutoConfiguration
org.springframework.boot.jackson.autoconfigure.JacksonAutoConfiguration
com.ankurm.traps.OrderedModuleAutoConfiguration

Marker bean created by OrderedModuleAutoConfiguration

--- what Boot recorded ---
com.ankurm.traps.EarlyModuleAutoConfiguration  [not matched]
    did not match: @ConditionalOnBean (types: tools.jackson.databind.json.JsonMapper; SearchStrategy: all) did not find any beans of type tools.jackson.databind.json.JsonMapper
com.ankurm.traps.OrderedModuleAutoConfiguration  [matched]
    matched: @ConditionalOnBean (types: tools.jackson.databind.json.JsonMapper; SearchStrategy: all) found bean 'jacksonJsonMapper'

The failure is silent, and it depends on your package name. Nothing throws. The bean the class would have defined is simply missing, and the same code works or fails depending on how its package sorts against Boot’s. Rename com.ankurm to org.zzz and the broken class would sort after Boot’s and pass, which is how a starter can work in its author’s tests and fail for a consumer whose other auto-configurations shift the order. Any condition on a bean that another auto-configuration creates needs an explicit after or afterName. I did not run the renamed variant; the sentence follows from the sort order shown above.

Going deeper

• Boot reference: locating auto-configuration candidates
• Boot reference: bean conditions and their ordering caveat

Testing with ApplicationContextRunner, and the test that passes while the starter is broken

private final ApplicationContextRunner runner = new ApplicationContextRunner()
        .withInitializer(new ConditionEvaluationReportLoggingListener())
        .withConfiguration(AutoConfigurations.of(JacksonAutoConfiguration.class,
                MaskerAutoConfiguration.class, MaskerJacksonAutoConfiguration.class));

@AutoConfiguration
public class ForgottenAutoConfiguration {

    @Bean
    String forgottenMarker() {
        return "created by ForgottenAutoConfiguration";
    }
}

--- ApplicationContextRunner: the test names the class itself ---
forgottenMarker bean   : true

--- the starter author's application: @SpringBootApplication scanning the package that holds both classes ---
forgottenMarker        (@AutoConfiguration) : false
forgottenPlainMarker   (@Configuration)     : true

--- a consumer application: its own package, the starter on the classpath ---
forgottenMarker        (@AutoConfiguration) : false
forgottenPlainMarker   (@Configuration)     : false
Masker beans                                : [masker]

A green runner test proves nothing about the imports file. The runner found the class because the test named it. Neither application found it: not the consumer, which is what you would expect, and not the author’s own application either, whose scan covers the package the class sits in. A plain @Configuration class in the same place was picked up by that scan, which is a worse outcome: it works for the author and disappears for everyone else. And the spring.factories entry did nothing. The imports file is the only registration Boot 4 honours for auto-configuration classes, in this run and per the reference, which says they must be loaded only by being named there.

void aTestThatReadsTheImportsFileCatchesTheOmission() {
    try (Transcript t = new Transcript("09-reading-the-imports-file-in-a-test.txt",
            "ImportCandidates: what Boot itself reads from META-INF/spring/...AutoConfiguration.imports")) {
        var candidates = ImportCandidates.load(AutoConfiguration.class, getClass().getClassLoader()).getCandidates();
        var ours = candidates.stream().filter(c -> c.startsWith("com.ankurm.masker.")).toList();
        t.line("entries under com.ankurm.masker: %d", ours.size());
        ours.forEach(c -> t.line("  %s", c));
        t.line("ForgottenAutoConfiguration listed: %s", candidates.contains(ForgottenAutoConfiguration.class.getName()));
        assertThat(ours).containsExactlyInAnyOrder(MaskerAutoConfiguration.class.getName(),
                MaskerJacksonAutoConfiguration.class.getName());
    }
}

entries under com.ankurm.masker: 2
  com.ankurm.masker.MaskerAutoConfiguration
  com.ankurm.masker.MaskerJacksonAutoConfiguration
ForgottenAutoConfiguration listed: false

ldc #26 // class org/springframework/context/annotation/Configuration
ldc #40 // class org/springframework/boot/autoconfigure/AutoConfiguration
ldc #40 // class org/springframework/boot/autoconfigure/AutoConfiguration
invokestatic #65 // Method org/springframework/boot/context/annotation/ImportCandidates.load:(Ljava/lang/Class;Ljava/lang/ClassLoader;)Lorg/springframework/boot/context/annotation/ImportCandidates;

Going deeper

• Boot reference: testing your auto-configuration
• ApplicationContextRunner Javadoc
• All the tests: the test package

What Boot 4 changed for people writing starters

--- entries in spring-boot-autoconfigure's own AutoConfiguration.imports ---
12

--- JacksonAutoConfiguration: which jar, which package ---
spring-boot-autoconfigure-4.1.1.jar, classes named JacksonAutoConfiguration: 0
spring-boot-jackson-4.1.1.jar: org/springframework/boot/jackson/autoconfigure/JacksonAutoConfiguration.class

import org.springframework.boot.autoconfigure.jackson.JacksonAutoConfiguration;

/** How a Boot 3 starter orders itself after Jackson. Not part of the build: scripts/capture-jar-facts.sh compiles it on purpose. */
@AutoConfiguration(after = JacksonAutoConfiguration.class)
public class OldJacksonImport {
}

masker-spring-boot-autoconfigure/src/broken/OldJacksonImport.java:4: error: package org.springframework.boot.autoconfigure.jackson does not exist
import org.springframework.boot.autoconfigure.jackson.JacksonAutoConfiguration;
                                                     ^
masker-spring-boot-autoconfigure/src/broken/OldJacksonImport.java:7: error: cannot find symbol
@AutoConfiguration(after = JacksonAutoConfiguration.class)
                           ^
  symbol: class JacksonAutoConfiguration
2 errors

spring-boot-autoconfigure-4.1.1.jar            org/springframework/boot/autoconfigure/AutoConfiguration.class
spring-boot-autoconfigure-4.1.1.jar            org/springframework/boot/autoconfigure/AutoConfigureAfter.class
spring-boot-autoconfigure-4.1.1.jar            org/springframework/boot/autoconfigure/AutoConfigurations.class
spring-boot-autoconfigure-4.1.1.jar            org/springframework/boot/autoconfigure/condition/ConditionalOnClass.class
spring-boot-autoconfigure-4.1.1.jar            org/springframework/boot/autoconfigure/condition/ConditionalOnBean.class
spring-boot-autoconfigure-4.1.1.jar            org/springframework/boot/autoconfigure/condition/ConditionalOnMissingBean.class
spring-boot-autoconfigure-4.1.1.jar            org/springframework/boot/autoconfigure/condition/ConditionalOnProperty.class
spring-boot-autoconfigure-4.1.1.jar            org/springframework/boot/autoconfigure/logging/ConditionEvaluationReportLoggingListener.class
spring-boot-4.1.1.jar                          org/springframework/boot/context/annotation/ImportCandidates.class
spring-boot-4.1.1.jar                          org/springframework/boot/context/annotation/Configurations.class
spring-boot-jackson-4.1.1.jar                  org/springframework/boot/jackson/autoconfigure/JacksonAutoConfiguration.class
spring-boot-test-4.1.1.jar                     org/springframework/boot/test/context/runner/ApplicationContextRunner.class
spring-boot-test-4.1.1.jar                     org/springframework/boot/test/context/FilteredClassLoader.class

Going deeper

• Spring Boot 3 to 4 migration guide for the wider modularisation and package changes
• Boot reference: creating your own auto-configuration

Should you write a starter at all?

Not for one application. A starter is a second artifact with its own version, its own release process and its own compatibility matrix against Boot, and every application that depends on it inherits the consequences of each Boot upgrade you have not yet made. If only one application needs the beans, a @Configuration class inside it costs nothing and needs no imports file. Two applications is the point at which duplication starts to drift, and three is the point at which a starter usually pays for itself. Before writing one, check whether the thing you are wrapping already has an official or vendor starter, because the property namespace you would invent will not match the one your colleagues meet next.

If you do write one, keep it small, make everything overridable with @ConditionalOnMissingBean, make the off switch obvious, and put the transcripts in the README so a reader can see what it did in a real run. The starter in this repository is about 130 lines of Java, and most of what is written above is about the ways those lines go wrong quietly.

Going deeper

• Run everything yourself: the module README has the quick-start and an index of the seventeen transcripts; ./scripts/run-all.sh regenerates them

Further reading

• Companion repository for this article: asmhatre/spring-boot-demo, custom-starter module
• On this site: @ConfigurationProperties vs @Value in Spring Boot 4, Dependency Injection in Spring Boot 4, Spring Boot 3 to 4 migration guide, Why Your Spring Boot App Takes 8 Seconds to Start
• Spring Boot reference: Creating Your Own Auto-configuration
• Spring Boot reference: configuration metadata
• ApplicationContextRunner Javadoc
• Spring Boot reference: externalized configuration