# DecomposeExperimentFlags in Decompose: Purpose, Deprecation, and Migration Guide

> Learn about DecomposeExperimentFlags in the arkivanov/decompose library. Understand its purpose, deprecation, and how to migrate to the stable DecomposeSettings API for cleaner duplicate configuration handling.

- Repository: [Arkadii Ivanov/decompose](https://github.com/arkivanov/decompose)
- Tags: migration-guide
- Published: 2026-02-25

---

**DecomposeExperimentFlags is a deprecated Kotlin object in the arkivanov/decompose library that historically provided temporary opt-in access to experimental duplicate configuration handling, now replaced by the stable DecomposeSettings API.**

DecomposeExperimentFlags served as a transitional configuration mechanism within the Decompose library for Android and Kotlin Multiplatform navigation. This experimental flags object allowed developers to enable unstable features before they graduated to stable APIs, specifically controlling duplicate configuration detection during child navigation operations.

## What Is DecomposeExperimentFlags?

### Historical Role in Feature Rollouts

DecomposeExperimentFlags acted as a thin wrapper exposing boolean switches for capabilities still under development. The object provided a controlled mechanism for library maintainers to surface experimental behavior while keeping the public API surface minimal and stable.

### The duplicateConfigurationsEnabled Property

The sole member of this object, `duplicateConfigurationsEnabled`, controlled whether the navigation system would handle duplicate configurations within child stacks. When enabled, this feature allowed multiple children in a navigation stack to share identical configuration states, which was particularly useful for advanced routing scenarios involving repeated screens.

## Why DecomposeExperimentFlags Was Deprecated

### Graduation to Stable API

When duplicate configuration handling matured into a stable feature, the experimental flag became redundant. The Decompose library introduced `DecomposeSettings` as a centralized, type-safe configuration holder, rendering the temporary flag-based approach obsolete.

### Current Architecture

The deprecated `DecomposeExperimentFlags` object now functions as a compatibility proxy. All reads and writes to `duplicateConfigurationsEnabled` redirect to `DecomposeSettings.settings.duplicateConfigurationsEnabled`, ensuring backward compatibility while guiding developers toward the modern API.

## Migrating from DecomposeExperimentFlags to DecomposeSettings

### Legacy Implementation (Deprecated)

The following approach using `DecomposeExperimentFlags` still compiles but generates deprecation warnings:

```kotlin
import com.arkivanov.decompose.DecomposeExperimentFlags

// Enable duplicate configurations using the deprecated experimental flag
DecomposeExperimentFlags.duplicateConfigurationsEnabled = true

```

### Modern Implementation (Recommended)

Use `DecomposeSettings` for atomic, thread-safe configuration updates:

```kotlin
import com.arkivanov.decompose.DecomposeSettings

// Atomic update using the update function
DecomposeSettings.update {
    it.copy(duplicateConfigurationsEnabled = true)
}

// Direct assignment (not thread-safe, use with caution)
DecomposeSettings.settings = DecomposeSettings.settings.copy(
    duplicateConfigurationsEnabled = true
)

```

### Runtime Checking

Library internals and user code should check the setting through the stable API:

```kotlin
import com.arkivanov.decompose.DecomposeSettings

if (DecomposeSettings.settings.duplicateConfigurationsEnabled) {
    // Execute logic that supports duplicate configurations
}

```

## Source Code Locations and Implementation Details

### Flag Definition

The experimental flag object resides in [`decompose/src/commonMain/kotlin/com/arkivanov/decompose/DecomposeExperimentFlags.kt`](https://github.com/arkivanov/decompose/blob/main/decompose/src/commonMain/kotlin/com/arkivanov/decompose/DecomposeExperimentFlags.kt). This file contains the deprecated object declaration with the `duplicateConfigurationsEnabled` property annotated with `@Deprecated` and `@ExperimentalDecomposeApi`, which proxies to `DecomposeSettings`.

### Global Settings

The stable configuration holder is defined in [`decompose/src/commonMain/kotlin/com/arkivanov/decompose/DecomposeSettings.kt`](https://github.com/arkivanov/decompose/blob/main/decompose/src/commonMain/kotlin/com/arkivanov/decompose/DecomposeSettings.kt). This file implements the atomic `update()` function and holds the actual `duplicateConfigurationsEnabled` state as part of the `Settings` data class.

### Navigation Integration

The flag is consumed during child navigation operations in [`decompose/src/commonMain/kotlin/com/arkivanov/decompose/router/children/ChildrenNavigator.kt`](https://github.com/arkivanov/decompose/blob/main/decompose/src/commonMain/kotlin/com/arkivanov/decompose/router/children/ChildrenNavigator.kt). This file demonstrates how the library checks `DecomposeSettings.settings.duplicateConfigurationsEnabled` when determining whether to allow duplicate configurations in navigation stacks.

## Summary

- **DecomposeExperimentFlags** provided temporary opt-in access to experimental duplicate configuration handling in the Decompose library.
- The object is now **deprecated** and functions as a compatibility proxy that delegates to the stable **DecomposeSettings** API.
- Developers should migrate to `DecomposeSettings.update()` for atomic, thread-safe configuration changes.
- Key implementation files include [`DecomposeExperimentFlags.kt`](https://github.com/arkivanov/decompose/blob/main/DecomposeExperimentFlags.kt) (legacy proxy), [`DecomposeSettings.kt`](https://github.com/arkivanov/decompose/blob/main/DecomposeSettings.kt) (stable settings), and [`ChildrenNavigator.kt`](https://github.com/arkivanov/decompose/blob/main/ChildrenNavigator.kt) (runtime usage).

## Frequently Asked Questions

### Is DecomposeExperimentFlags still safe to use in production code?

While the object still functions as a compatibility proxy, it is marked with `@Deprecated` and `@ExperimentalDecomposeApi` annotations. You should migrate to `DecomposeSettings` immediately, as the experimental flag may be removed in future releases without additional warning.

### What is duplicate configuration handling in Decompose?

Duplicate configuration handling allows multiple children in a navigation stack to share identical configuration states. This capability is useful for scenarios like displaying the same screen type multiple times in a stack with different instances, which was previously restricted to prevent configuration collisions.

### How do I check if duplicate configurations are enabled at runtime?

Access the current state through `DecomposeSettings.settings.duplicateConfigurationsEnabled`. This property reflects the global configuration and is checked internally by navigation components like `ChildrenNavigator` when processing child stack operations.

### Why was DecomposeExperimentFlags replaced by DecomposeSettings?

The transition follows standard library evolution patterns. `DecomposeSettings` provides type safety, atomic updates via the `update()` function, and a stable API surface, whereas `DecomposeExperimentFlags` was intended only as a temporary opt-in mechanism during the feature incubation period.