DecomposeExperimentFlags in Decompose: Purpose, Deprecation, and Migration Guide

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:

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:

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:

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. 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. 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. 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 (legacy proxy), DecomposeSettings.kt (stable settings), and 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}