This is a Spring Boot starter that integrates OpenFeature, an open standard for feature flag
management. Add one starter dependency, set a few spring.openfeature.* properties, and feature flags work in your
application — no manual wiring of the OpenFeature SDK.
- Auto-Configuration — a ready-made
dev.openfeature.sdk.Clientbean, created as soon as aFeatureProviderbean is on the context. - Declarative Flags — the
@ToggleOnFlagannotation gates method execution on a flag, with SpEL evaluation context and anorElsefallback method. - Health Indicator — a Spring Boot Actuator health check for the configured flag provider.
- Provider Starters — one starter module per feature-flag backend, each configured under its own
spring.openfeature.<provider>.*prefix. - Extension Points —
ClientCustomizer,OpenFeatureAPICustomizer, and per-provider customizers let you tweak the auto-configured beans. - Security Integration — when Spring Security is on the classpath,
userIdandauthoritiesare automatically added to every flag evaluation context.
- Java 17
- Maven (the repository ships the Maven wrapper
./mvnw)
Every provider has its own starter. For Unleash:
Maven
<project>
<dependencies>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-web</artifactId>
</dependency>
<dependency>
<groupId>org.iromu.openfeature</groupId>
<artifactId>spring-boot-starter-openfeature-unleash</artifactId>
</dependency>
</dependencies>
<dependencyManagement>
<dependencies>
<dependency>
<groupId>org.iromu.openfeature</groupId>
<artifactId>spring-boot-openfeature-dependencies</artifactId>
<version>${spring-boot-openfeature.version}</version>
<type>pom</type>
<scope>import</scope>
</dependency>
</dependencies>
</dependencyManagement>
</project>Gradle
dependencyManagement {
imports {
mavenBom "org.iromu.openfeature:spring-boot-openfeature-dependencies:${springBootOpenFeatureVersion}"
}
}
dependencies {
implementation 'org.springframework.boot:spring-boot-starter-web'
implementation 'org.iromu.openfeature:spring-boot-starter-openfeature-unleash'
}The BOM (spring-boot-openfeature-dependencies) pins the OpenFeature SDK and every provider library version, so you
do not need to declare versions yourself.
Configure the provider under its spring.openfeature.<provider>.* prefix in application.yml (or
application.properties). For example, Unleash:
spring:
application:
name: UnleashApplication
openfeature:
unleash:
app-name: ${spring.application.name}
environment: development
unleash-api: http://unleash-instance:4242/api/
unleash-token: 'default:development.your-api-key'Each provider starter also accepts an enabled property (spring.openfeature.<provider>.enabled) to switch its
auto-configuration on or off. See the provider table below for the full set of options
per provider.
Inject the auto-configured Client and evaluate flags:
import dev.openfeature.sdk.Client;
import dev.openfeature.sdk.ImmutableContext;
import dev.openfeature.sdk.Value;
@RestController
@RequestMapping("/feature")
public class FeatureController {
private final Client client;
public FeatureController(Client client) {
this.client = client;
}
@GetMapping("{name}")
public Boolean feature(@PathVariable("name") final String name) {
return this.client.getBooleanValue(name, false);
}
@GetMapping("user/{id}")
public Boolean featureOnUserId(@PathVariable("id") final String id) {
return this.client.getBooleanValue("users-flag", false,
new ImmutableContext(Map.of("userId", new Value(id))));
}
}The @ToggleOnFlag annotation (from org.iromu.openfeature.boot.aop) conditionally executes a method based on a
flag. attributes accepts a SpEL map that is evaluated into the flag evaluation context, and orElse names a
fallback method invoked when the flag evaluates to false.
Given an Unleash flag defined as:
{
"name": "users-flag",
"enabled": true,
"strategies": [
{
"name": "userWithId",
"parameters": {
"userIds": "111,234"
}
}
]
}import org.iromu.openfeature.boot.aop.ToggleOnFlag;
@RestController
@RequestMapping("/feature")
public class UserController {
@GetMapping("annotated/user/{id}")
@ToggleOnFlag(key = "users-flag", attributes = "{'userId': #id}", orElse = "featureOnUserIdDisabled")
public String featureOnUserIdAnnotated(@PathVariable("id") final String id) {
return "User allowed";
}
public String featureOnUserIdDisabled(final String id) {
return "User not allowed";
}
}Each backend has its own starter module under org.iromu.openfeature:
| Provider | Version | Starter artifact | Documentation |
|---|---|---|---|
| Ageris | 0.7.0 | spring-boot-starter-openfeature-ageris |
README |
| ConfigCat | 0.2.1 | spring-boot-starter-openfeature-configcat |
README |
| ConfigDirector | 1.4.0 | spring-boot-starter-openfeature-configdirector |
README |
| Confidence | 0.7.0 | spring-boot-starter-openfeature-confidence |
README |
| Datadog | 1.68.1 | spring-boot-starter-openfeature-datadog |
README |
| DevCycle | 2.10.0 | spring-boot-starter-openfeature-devcycle |
README |
| Env Var | 0.0.12 | spring-boot-starter-openfeature-envvar |
README |
| FeatBit | 1.0.0 | spring-boot-starter-openfeature-featbit |
README |
| flagd | 0.15.0 | spring-boot-starter-openfeature-flagd |
README |
| Flagsmith | 0.0.13 | spring-boot-starter-openfeature-flagsmith |
README |
| Flipt | 0.1.4 | spring-boot-starter-openfeature-flipt |
README |
| Featureflip | 0.2.1 | spring-boot-starter-openfeature-featureflip |
README |
| GCP | 0.0.2 | spring-boot-starter-openfeature-gcp |
README |
| GoFeatureFlag | 2.0.2 | spring-boot-starter-openfeature-gofeatureflag |
README |
| GrowthBook | 0.0.2 | spring-boot-starter-openfeature-growthbook |
README |
| JsonLogic | 1.3.0 | spring-boot-starter-openfeature-jsonlogic |
README |
| Kameleoon | 0.0.1 | spring-boot-starter-openfeature-kameleoon |
README |
| LaunchDarkly | 2.0.0 | spring-boot-starter-openfeature-launchdarkly |
README |
| Mixpanel | 0.2.0 | spring-boot-starter-openfeature-mixpanel |
README |
| Multi-Provider | 0.0.3 | spring-boot-starter-openfeature-multiprovider |
README |
| OFREP | 0.0.2 | spring-boot-starter-openfeature-ofrep |
README |
| Optimizely | 1.0.0 | spring-boot-starter-openfeature-optimizely |
README |
| Octopus Deploy | 2.1.0 | spring-boot-starter-openfeature-octopusdeploy |
README |
| Statsig | 0.2.1 | spring-boot-starter-openfeature-statsig |
README |
| Split | 1.2.2 | spring-boot-starter-openfeature-split |
README |
| Superposition | 0.118.2 | spring-boot-starter-openfeature-superposition |
README |
| Unleash | 0.1.3-alpha | spring-boot-starter-openfeature-unleash |
README |
| VWO | 1.0.0 | spring-boot-starter-openfeature-vwo |
README |
| CloudBees | 1.0.1 | spring-boot-starter-openfeature-cloudbees |
README |
To switch providers, replace the starter dependency and update the configuration as described in the provider's README.
The examples/ directory contains thirty runnable applications (built with the examples profile or as a separate
reactor; they resolve the starters from the local build or the snapshot repository):
unleash-simple— port9998; in-memory fake Unleash provider (default, no external server needed).unleash-advanced— port9999; mocked Unleash API server with a localfeatures.jsonbackup file.- one
<provider>-simpleper remaining provider (28 apps:ageris-simple,cloudbees-simple,confidence-simple,configcat-simple,configdirector-simple,datadog-simple,devcycle-simple,featbit-simple,featureflip-simple,flipt-simple,flagd-simple,flagsmith-simple,gcp-simple,gofeatureflag-simple,growthbook-simple,jsonlogic-simple,kameleoon-simple,launchdarkly-simple,mixpanel-simple,multiprovider-simple,octopusdeploy-simple,ofrep-simple,optimizely-simple,split-simple,statsig-simple,superposition-simple,vwo-simple) — port9999; each boots credential-free with an in-memory fake provider (--example.fake-provider=true).
$ cd examples
$ mvn clean packageThen run the packaged application, for example:
$ java -jar unleash-simple/target/unleash-simple-${revision}.jar
$ java -jar gcp-simple/target/gcp-simple-${revision}.jar --example.fake-provider=trueTry the endpoints (unleash-simple on 9998):
$ curl http://localhost:9998/feature/random-boolean-flag
$ curl http://localhost:9998/feature/greet/worldThe "simple" examples all expose the same endpoints on their respective ports:
$ curl http://localhost:9999/feature/random-boolean-flag
$ curl http://localhost:9999/feature/toggle/random-boolean-flag
$ curl http://localhost:9999/feature/greet/worldAnd with unleash-advanced running on 9999:
$ curl http://localhost:9999/feature/annotated/user/111All commands use the Maven wrapper from the repository root:
# Full build (compile, checkstyle, formatting, tests, coverage)
$ ./mvnw clean verify
# Skip tests
$ ./mvnw clean verify -DskipTests
# Build a single module and its dependencies
$ ./mvnw -pl spring-boot-starter-openfeature-unleash -am clean verifyCode style is enforced by Spring Java Format and Checkstyle, which run automatically during the validate phase.
Design and engineering documents live under docs/:
| Document | Contents |
|---|---|
| architecture.md | Module map, the provider → Client wiring flow, extension points, @ToggleOnFlag aspect, health and security integration |
| provider-starter-contract.md | The shared auto-configuration contract every provider starter honors, per-provider deltas, and the checklist for adding a starter |
| quality-and-testing.md | Test tiers, behavioral contracts, per-module JaCoCo coverage floors, CI posture and known gaps |
| dependency-management.md | Where versions live, the BOM, the OpenFeature SDK ↔ provider lockstep rule, upgrade policy and blocked pins |
| backlog.md | Unimplemented work: the blocked Featurevisor and Hyphen AI starters, the Unleash real-endpoint CI gate |
| dependency-versions.md | Generated audit of every plugin and dependency pin against its latest release |
Contributions are welcome! See CONTRIBUTING.md for the full guide on reporting bugs, suggesting features, code style, testing, and the pull request process.
This project is licensed under the Apache License 2.0. See the LICENSE file for details.