Boost Spring Startup Speed with spring-context-indexer: A Complete Guide

Environment: Spring 5.3.23

1. Introduction

In large Spring projects, registering hundreds of beans via class‑path scanning can slow down application startup. The spring‑context‑indexer creates an index of components at compile time, allowing the container to load them quickly and significantly improve startup speed.

2. Configuration

Adding the Maven dependency

<dependency>
  <groupId>org.springframework</groupId>
  <artifactId>spring-context-indexer</artifactId>
  <version>5.3.23</version>
  <optional>true</optional>
</dependency>

If you use Gradle:

# Gradle 4.5 and below
dependencies {
  compileOnly "org.springframework:spring-context-indexer:5.3.23"
}
# Gradle 4.6 and above
dependencies {
  annotationProcessor "org.springframework:spring-context-indexer:5.3.23"
}

Preparing bean classes

@Component
public class Person { }

@Component
public class Student { }

@Component
public class User { }

Testing that the classes are discovered

try (AnnotationConfigApplicationContext context =
        new AnnotationConfigApplicationContext("com.pack.context_indexed")) {
    for (String name : context.getBeanDefinitionNames()) {
        System.out.println(name);
    }
}

Console output shows the framework’s internal processors followed by person, student, and user, confirming that all beans are scanned.

Manual index file creation

Create META-INF/spring.components with entries in the form full.package.Class=full.annotation.Name:

com.pack.context_indexed.Person=org.springframework.stereotype.Component

After adding this file, only person is loaded because the index lists only that bean.

Custom annotation support

// Custom annotation
@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.TYPE)
@Component
public @interface PackComponent { }

// Apply to a bean
@PackComponent
public class User { }

Add the custom mapping to the index file:

com.pack.context_indexed.Person=org.springframework.stereotype.Component
com.pack.context_indexed.User=com.pack.context_indexed.PackComponent

Running the test now prints person and user.

Automatic index generation (Eclipse example)

Configure the spring‑context‑indexer as an annotation processor in Eclipse. After building, the spring.components file is generated under target/classes/META-INF with entries for all @Component classes:

com.pack.context_indexed.Person=org.springframework.stereotype.Component
com.pack.context_indexed.Student=org.springframework.stereotype.Component
com.pack.context_indexed.User=org.springframework.stereotype.Component

Disabling the index

Set the JVM option -Dspring.index.ignore=true to turn off indexing.

In summary, spring‑context‑indexer reduces startup time in large Spring applications by generating a compile‑time component index, which the container can read quickly, leading to faster development cycles, lower resource consumption, and fewer runtime errors.