Build Your Own Starter: From Zero to Auto-Loaded

This article is not about using Spring Boot — it is about building the thing that makes Spring Boot light up for somebody else when they merely add a dependency. You write a capability (say, sending SMS), package it as a jar, and the consumer only adds one <dependency> block plus a few lines of yml before injecting it like a built-in component. In Spring Boot that package is called a starter.

Six terms you will see immediately, defined once here:

After this article you should be able to answer three questions:

• Do my Java classes belong in the starter module or the autoconfigure module, and which error message do I get if I choose wrong?
• How does the container even learn that my third-party configuration class exists — which file, and how exact must its path be?
• If a consumer wants to switch my starter off, or replace my default with their own implementation, what hook did I have to leave in place?

After adding spring-boot-starter-web, you write no configuration at all, yet you suddenly have embedded Tomcat, Spring MVC, Jackson serialization… Many people's first reaction is "this starter is magic". But open its pom and you find a counter-intuitive fact: the starter jar contains not a single line of Java.

Spring Boot officially splits "starter" into two things with completely different jobs:

The spring-boot-starter-web pom (trimmed) looks roughly like this:

Let's build an "SMS sending" starter from scratch. The goal is concrete: the consumer adds the dependency, writes a few lines of yml, and can immediately @Autowired SmsClient.

Following official guidance, split into two modules:

The autoconfigure pom: the key point is to mark compile-time-only dependencies as optional:

The starter pom only carries the autoconfigure module:

Which boxes to tick in those two poms is worth generating once yourself rather than copying, because every scope and every optional in the output traces back to one rule in this section:

Two modules are up; now, what does each of the four files actually own? That relationship is easier to mix up than the poms, so here it is as a stack you can click from the bottom up — remove one layer and the consumer's experience loses exactly one feature:

The properties class binds sms.* from yml into a Java object. It is the starter's "parameter panel":

The properties class is only the cup; the animation below shows how the water arrives. Six beats from one yml line to a live SmsClient — pay attention to beat ③, because that is the moment access-key and accessKey finally meet:

SmsClient is the capability the starter actually exposes. The key insight: it is a plain POJO that registers nothing.

This is the soul of the starter: it decides when to register SmsClient into the container.

Annotation by annotation — this is how you read and write auto-configuration:

• @AutoConfiguration: the new marker, equivalent to @Configuration(proxyBeanMethods = false) but gaining ordering (before / after). It must be registered via the imports list and cannot be picked up by @ComponentScan
• @ConditionalOnClass(SmsClient.class): the class must exist on the classpath. This is exactly the switch for "skip the whole auto-configuration when the dependency is absent"
• @ConditionalOnProperty(prefix = "sms", name = "enabled", havingValue = "true", matchIfMissing = true): gives the consumer a master switch; matchIfMissing = true means "on by default even if not written in yml"
• @EnableConfigurationProperties(SmsProperties.class): registers SmsProperties as a bean and binds it, so the @Bean method below can simply take a parameter
• @ConditionalOnMissingBean (on the @Bean method): the embodiment of user first — if the consumer defines their own SmsClient, this steps aside; only when none exists does it provide the fallback

Those five annotations each own exactly one job, and those five jobs are what interviewers and tickets keep asking about. Lists are not memorable, so play a round: pick the annotation you wrote, then the one thing it is responsible for.

The auto-configuration class is written, but how does the container learn about it? Through a list file whose path must be exact:

Its content is trivially simple, one class name per line, with no key at all:

Somebody always asks: why not put @ComponentScan on the auto-configuration class and sweep your own package in? It is less typing, yes — but it hands "when is a condition evaluated" back to scan order and takes it away from the container. Here is the difference between the two doors; through the left one, @ConditionalOnMissingBean can answer "none" far too early:

Once the starter is done, the consumer does only three things.

First, add the dependency:

Second, write the configuration:

Third, use it directly:

A line of console output after startup proves the wiring worked:

When a starter "does not work", do not guess — turn on the condition report:

Find your own configuration class in the report and check each condition:

The official guidance on custom starters is explicit; follow it to avoid many traps:

The demo below turns those three conditions into switchable knobs. Toggle "user already customized" and watch the registration of SmsClient get skipped:

All four files are written; now connect them in startup order. This chain is the hardest part to derive on your own, and it is also the skeleton of the interview answer "walk me through how a custom starter works":

That table is for reading; order still has to be clicked. Here are the same five steps as a single-step run: six lines on the left, variables and call stack refreshing on the right. Step through and stop on beat ② — that beat decides whether the other four ever get a chance to happen:

Pictures alone do not make the wiring chain stick, because it runs inside the first seconds of startup and never shows you an object. These five labs genuinely execute Spring Boot's layers in your browser, and each lets you flip parameters. Suggested order: ① for the overall picture, ② for registration and ordering, ③ for the condition annotations one at a time, ④ for how the consumer's configuration actually reaches SmsProperties, and ⑤ to settle which door SmsProperties and SmsClient each came in through.

The first lab takes apart the starter's four load-bearing columns. Metadata means "data describing your own configuration" — here, that imports list. Press the four buttons in order and you watch "list present → properties bound → bean created → I switch it off"; the last button is exactly where the decision card in Section 12 lands, giving consumers a graceful way to opt out:

The second lab answers the most abstract part of step 2: which jars the candidate list is harvested from, and why the harvest has to be sorted. The "sorting" step reveals the before / after relations among the official auto-configurations — this is precisely what @AutoConfiguration adds over a bare @Configuration, and your third-party class is ordered after all official ones by default:

The third lab evaluates the three condition annotations from Section 5 individually. A conditional annotation is simply a gate that says "wire this only if the condition holds". Switch to @ConditionalOnMissingBean and watch the default implementation get skipped once the user has defined a bean of the same type — the very thing the sandbox in Section 15 asks you to verify by hand:

The fourth lab answers the sentence consumers ask most: "I wrote access-key in yml, my Java field is accessKey — how do those match?" Relaxed binding is the ability of @ConfigurationProperties to let kebab-case, camelCase and upper-case environment variables all hit the same field. While you are there, compare "who overrides whom" to see the priority relation among profile, environment variable and command line:

The fifth lab answers a sentence nobody spells out: SmsProperties and SmsClient are both beans, but they did not come in through the same door. Click scan, bean, import, auto in turn — component scanning, an @Bean method, a direct @Import, and list-registered auto-configuration — and each prints the moment it writes its BeanDefinition. Your properties class takes the "direct" route via @EnableConfigurationProperties, SmsClient takes the @Bean route, and the auto-configuration class itself came in through the list. Then click miss and see why "the package was never scanned" and "the list was never read" produce the identical complaint:

Enough buttons; type the commands yourself instead. This console talks to the same in-browser kernel and every reply is computed there:

This sandbox simulates the final state of the consumer's project. Two knobs on the left: how sms.enabled is written, and whether the consumer defined a bean of the same type. The right panel immediately reports which SmsClient the container ends up holding, and whether the injection point blows up.

State the conclusion first: a well-designed starter exposes two hooks — switchable-off (sms.enabled) and replaceable (@ConditionalOnMissingBean). The first lets the consumer express intent in their own application.yml; the second guarantees the user's customization always beats your default. That is the payoff of the annotation-by-annotation reading in Section 5.

Every phrase in the first column can be pasted straight into a search box — do not paraphrase or shorten it. The last column says where to dig deeper.

The last two rows of that table only become distinguishable once you have clicked a real stack. This is the ticket starter authors receive most: dependency added, yml written, and the bean is still "not found". Do not read the analysis — pick the frame you believe is guilty:

Goal: in fifteen minutes build a minimal working starter and walk all four states — "add dependency → live → switched off → not live".

The consumer's application.yml and the expected output:

Done when: ① setting echo.enabled to false makes the injection point throw NoSuchBeanDefinitionException; ② jar tf shows .class files plus the imports file inside the autoconfigure jar while the starter jar holds only a pom; ③ you can explain why deleting the setter silently restores the default value.

Each variant changes exactly one thing, and each has its own observation point:

1. Add @Min(100) private int delay = 500; to EchoProperties but do not add @Validated. You will observe that writing echo.delay: 50 still starts cleanly — the trap from Section 3, validation silently disabled; after adding class-level @Validated, startup fails with must be greater than or equal to 100.
2. Move the imports file from META-INF/spring/ up to META-INF/ (only relocate it; content unchanged). You will observe no error at all at startup, yet EchoService no longer exists, and --debug output does not even mention EchoAutoConfiguration — precisely the cause behind the second-to-last row of Section 16.
3. In the consumer project define your own @Bean EchoService, placing it once in a plain @Configuration class and once in a class annotated @AutoConfiguration. You will observe the former making @ConditionalOnMissingBean yield correctly, while the latter easily lands in the sandbox's "on + one exists" cell and produces two candidate beans.
4. Move @ConditionalOnProperty from class level onto the @Bean method, then set echo.enabled to false. You will observe EchoProperties still present (because @EnableConfigurationProperties remains on the class) while only EchoService disappears — the switch now governs a narrower scope.

Build an in-house starter: oss-spring-boot-starter, wrapping "object-storage upload" so it works out of the box.

• Structure must be two modules + four files (properties class, core service class, auto-configuration class, imports list), named per the Section 9 table
• Properties at least oss.enabled / oss.endpoint / oss.bucket / oss.access-key / oss.secret-key / oss.timeout, with @NotBlank on access-key and secret-key, @Min(500) on timeout, plus @Validated
• Ship an OssClient interface and one default implementation; the default's @Bean method must carry @ConditionalOnMissingBean so consumers can swap in their own mock
• Include additional-spring-configuration-metadata.json giving oss.enabled a description and a defaultValue so IDEs show hints
• Write an OssAutoConfigurationTest with ApplicationContextRunner covering four combinations: default on, enabled=false, user-supplied implementation, and startup failure when endpoint is missing

Acceptance checklist: ① a consumer injects OssClient with only a <dependency> plus five yml lines; ② --debug output shows one Positive match and one Negative match caused by enabled=false; ③ leaving access-key empty fails startup immediately and names that field; ④ when the consumer defines their own OssClient, theirs is the only one (prove it with doesNotHaveBean / hasSingleBean assertions); ⑤ dropping your starter into a brand-new project requires zero @Bean written by the consumer.