bytedance/scene: A Single Activity Framework That Keeps Fragments Working

The problem Scene was built to solve

Two Android primitives sit at the centre of this library's pitch: Activity and Fragment. The README states that an empty Activity's average startup time exceeds 100ms, and that Fragment has a compatibility problem because the Google Navigation Component destroys a Fragment's view when it becomes invisible. Those are the two claims the project is organised around. Scene answers both by moving navigation and page segmentation onto plain views, so a page is a Scene object that owns a View rather than an Activity task record or a Fragment managed by a FragmentManager.

The intended audience is an Android team already invested in the single-activity pattern. Scene does not ask you to throw away Fragment screens. The README lists Fragment compatibility as the first capability, and the repository ships a scene_fragment artifact plus a documented Fragment usage path. That combination is the actual selling point: you can introduce Scene incrementally, keep existing screens running, and migrate at your own pace. Teams starting a greenfield app with no legacy screens get less from that, since the migration story is the part that costs the library its simplicity.

How Scene's navigation stack and lifecycle actually work

A Scene is a view container with a lifecycle. You subclass Scene or AppCompatScene and return a View from onCreateContentView or onCreateView, exactly as the README's MainScene example does. SceneActivity is the host: you declare a home Scene class and, in the README's example, return false from supportRestore().

Navigation is a stack of Scenes held by a NavigationScene. The README's example calls navigationScene?.push(SecondScene()) from a button click, and SecondScene then calls add(mId, ChildScene(), "TAG") to nest a child Scene inside a view it owns. That is the composition model: push and pop move between pages, add and remove nest within a page. The README describes simple navigation stack management with support for multiple navigation stacks, which is the feature that separates Scene from a single back stack.

The lifecycle is enhanced and events are distributed, per the README's capability list. State is saved and restored through Parcelable, and Activity and Window properties can be modified and are automatically restored. For animation, the library supports cross-page and shared element transitions through a separate artifact. One design consequence is worth stating plainly: because a Scene is a view, a page that is pushed but not visible still has a view hierarchy unless you remove it. That is a different memory profile from an Activity, and it is also what makes shared element animation tractable.

Installing Scene from JitPack and pushing your first page

Scene is distributed through JitPack, not Maven Central. The README gives the repository block for both Groovy and Kotlin DSL; the Kotlin settings.gradle.kts form is the one to use on a modern Android project.

//settings.gradle.kts
dependencyResolutionManagement {
    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
    repositories {
        maven { url = uri("https://jitpack.io") }
    }
}

Then declare the dependency. The README lists a single artifact and a set of feature artifacts; pick only what you use, since scene_navigation, scene_ui, scene_dialog, scene_shared_element_animation and scene_ktx are separate modules.

//build.gradle.kts
dependencies {
    implementation("com.github.bytedance.scene:scene:$latest_version")
    implementation("com.github.bytedance.scene:scene_navigation:$latest_version")
}

The version placeholder is the README's own; the releases page carries the concrete tags, with v1.3.4 listed as the most recent. The minimum API level is 21 according to the README badge. No R8 or Proguard configuration is required, which is stated as a capability rather than explained, so treat it as a claim to confirm against your own shrinking setup.

Your host Activity inherits SceneActivity and names a home Scene. The README's example also overrides supportRestore to return false, which is worth noticing: restoration is opt-in at the host level.

class MainActivity : SceneActivity() {
    override fun getHomeSceneClass(): Class<out Scene> {
        return MainScene::class.java
    }

    override fun supportRestore(): Boolean {
        return false
    }
}

A first Scene returns its view from onCreateContentView and pushes the next page from a click listener. The README's MainScene does exactly this with navigationScene?.push(SecondScene()). To build the sample, the README gives one command for Linux: ./gradlew installDebug. If you want to look before you build, the repository links a sample APK under misc/latest_sample.apk.

The Dialog Window problem and other cases where Scene is the wrong tool

The README's Issues section names one failure mode directly. A normal Dialog's Window is independent and sits in front of the Activity's Window, so pushing a Scene while a Dialog is open puts the Scene behind the Dialog. The README's suggested workarounds are to close the dialog on click or to implement the dialog as a transparent Scene instead. That is not a bug report; it is a structural consequence of hosting pages in the Activity's Window, and it means any dialog-heavy flow needs rethinking before migration, not after.

The second limitation is ecosystem size. Scene is a library with a wiki and a sample, and the README's documentation section is a single link to that wiki. There is no large body of community answers to search when something goes wrong. A team that leans on Stack Overflow for Fragment problems will find much less material here.

The third is scope. Scene is for view-based UI. The README points Compose users at a wiki page rather than documenting an integration inline, so if your screens are Compose functions, the library's core value proposition, replacing Fragment and Activity navigation, is largely already handled by Compose navigation. The Fragment compatibility path is also a transitional tool, not a destination: keeping both models alive in one codebase has a cost, and the README describes migration solutions without spelling out the end state.

Scene compared with the Jetpack Navigation Component

The honest comparison is with the Jetpack Navigation Component, because the README criticises it by name: it destroys a Fragment's view when the Fragment becomes invisible. That behaviour is the design centre of the difference. Navigation Component is graph-first. You declare destinations and actions in XML or Kotlin DSL, and the library manages the back stack, arguments and deep links from that graph. Scene is stack-first. You hold a NavigationScene and call push and pop, and nesting is a direct add call with a view id and a tag, as in the README's SecondScene. There is no destination graph to declare.

That makes Scene more direct for imperative navigation and less capable for the things a graph gives you for free, such as deep-link parsing and a single place that describes every destination. The second difference is view retention. Because Navigation Component detaches a Fragment's view, state has to be hoisted into ViewModels or saved state. Scene keeps the view in the hierarchy, which simplifies shared element and cross-page animation, the use case the README highlights, and shifts the memory question to how many Scenes you keep pushed. Neither approach is strictly better; they optimise for different failure modes.

Maintenance status, release cadence and licence terms

The repository is not archived. The most recent push to master was on 2026-05-15, and the release list shows v1.3.4 on 2025-07-04, v1.3.3 two days earlier on 2025-07-02, and v1.3.2 on 2024-08-13. The pattern is long gaps punctuated by short bursts of patch releases, which matters if you need a fix turned around quickly: the gap between v1.3.2 and v1.3.3 is roughly eleven months. Budget for the possibility of carrying a local patch.

Upgrade cost is shaped by the module split. Because scene_navigation, scene_ui, scene_dialog, scene_shared_element_animation and scene_ktx are published separately, you can upgrade the core without moving the animation module, and you can also end up on mismatched versions across modules. Pin every Scene artifact to one version string rather than relying on a shared variable to drift.

The licence is Apache-2.0, per the repository's LICENSE file and the README badge. That is a permissive licence with an explicit patent grant and a requirement to preserve notices. It is not legal advice, and if you modify and redistribute the library, read the licence text and your own obligations rather than a summary.

Editorial conclusion

Adopt Scene if you are building or refactoring an Android app around a single Activity, you need multiple navigation stacks, and you want to keep existing Fragment screens working during a gradual migration. Do not adopt it if your app is Compose-only, if you depend on the Jetpack Navigation Component's graph and deep-link tooling, or if you need a large body of third-party tutorials to fall back on. Before committing, verify three things in the repository rather than the README: the wiki page for Compose, the migration guidance the README promises but does not inline, and the Dialog Window behaviour described in the Issues section against your own dialog usage. The last push to master was on 2026-05-15, and the most recent release listed is v1.3.4 on 2025-07-04, so check the release history against your target API level before you start.

Frequently asked questions

Official sources

1. bytedance/scene on GitHub
2. Issues
3. License: Apache-2.0
4. README
5. Releases