Documentation

HotSwan Preview Runner

Android Studio's built-in @Preview requires a full build every time you change anything: a composable parameter, a resource value, even a single color. On large projects this means anywhere from 30 seconds to 5 minutes of waiting per iteration.

In every scenario, isn't the preview lag you "always" run into kind of annoying?

Android Studio Compose Preview showing Out of date warning with stale renders

HotSwan's Preview Runner flips this entirely. Run your app once, and every subsequent preview renders on-device in under half a second. REAL physical device, real data, zero rebuild.

The Problem with Compose Preview

The standard Compose Preview in Android Studio has long been a pain point for Android developers:

1.

Full build on every single change

Change a font size, tweak a color, or update a string resource. It doesn't matter how small the edit is. Compose Preview triggers a full Gradle compilation every time, and on multi-module projects that can easily take 1 to 5 minutes per iteration.

2.

Heavy IDE tooling that slows everything down

The preview renderer runs inside the IDE process itself, consuming significant memory and CPU. The more previews you have, the slower your entire editor becomes. Code completion lags, indexing stalls, and the IDE feels unresponsive.

3.

Running on device takes even longer

Android Studio's “Run Preview on Device” option compiles a full test APK, installs it, and launches a test runner. This regularly takes over a minute, making rapid iteration impossible.

How It Works

HotSwan's Preview Runner takes a fundamentally different approach. Instead of rebuilding, it leverages the already-running app on your device and launches your @Preview composable directly via an Activity that is included in the debug build.

1

App is running

Your app is already installed and running on the device from a previous build. No additional compilation needed.

2

Click gutter icon

Click the HotSwan HotSwan icon in the editor gutter next to any @Preview function.

3

Instant render

The preview composable launches on-device in under 0.5 seconds via ADB intent. No build, no test APK, no waiting.

HotSwan leverages the same hot reload infrastructure that powers instant code changes. Because the app is already compiled and running on the device, there is no additional build step required to display a preview. The result is a near-instant rendering cycle that feels completely different from the traditional Compose Preview workflow.

Setup

Add the preview library to your app module's build.gradle.kts. This is a debugImplementation dependency, so it is completely excluded from release builds.

dependencies {
    // HotSwan Preview Runner (debug only)
    debugImplementation("com.github.skydoves.compose.hotswan:preview:<version>")
}

Replace <version> with the latest release version from the release notes. That's it. No annotation processors, no Gradle plugin changes, no manifest edits.

Running a Preview

Prerequisites: your app must be running on a connected device or emulator. HotSwan will show a notification if the app is not detected.

HotSwan gutter icon next to @Preview function

Open any Kotlin file containing an @Preview composable. You'll see the HotSwan HotSwan icon in the editor gutter, right next to the function declaration. Click it, and the preview renders on your device almost instantly.

The entire round trip, from click to pixels on screen, takes under 0.5 seconds. For composables that are already warm in memory, it can be as fast as 0.01 seconds.

Gradle Configuration

HotSwan provides a preview configuration block inside hotSwanCompiler for customizing the preview capture behavior:

hotSwanCompiler {
    preview {
        // Output directory for captured previews (relative to project root)
        outputDir.set(".hotswan/preview-captures")

        // Delay between launching a preview and capturing its screenshot
        renderDelayMs.set(2500L)

        // Enable SDK documentation mode for rich API docs
        sdkModeEnabled.set(false)
    }
}

outputDir

Directory where preview screenshots and the HTML catalog are saved. Relative to the project root. Default: .hotswan/preview-captures.

renderDelayMs

Milliseconds to wait after launching a preview before taking the screenshot. Increase this for composables that load data asynchronously. Default: 2500.

sdkModeEnabled

When enabled, the HTML catalog includes KDoc descriptions and parameter tables extracted from the composable that each preview wraps. Ideal for design system libraries. Default: false.

Capture All Previews

HotSwan includes a captureAllPreviews Gradle task that automatically finds every @Preview function in your project, launches each one on-device, captures a screenshot, and generates a browsable HTML catalog.

./gradlew captureAllPreviews

The task scans all .kt files under src/, detects @Preview annotations, and launches each composable on the connected device one by one. After all captures complete, an index.html file is generated in the default output directory: .hotswan/preview-captures/

HTML Catalog Features

The generated HTML catalog is a self-contained file you can open in any browser, share with your team, or host as documentation.

Dark / Light theme

Toggle between dark and light mode. Dark mode is the default.

Search

Filter previews by name or module with instant search.

Module grouping

Previews are grouped by Gradle module. Toggle grouping on or off with a single click.

Fullscreen modal

Click any preview screenshot to view it at full resolution in an overlay modal.

Device & timestamp info

Each report includes the device model, app package name, and generation timestamp.

SDK Documentation Mode

For design system and library/SDK developers, enable sdkModeEnabled to generate rich API documentation alongside your preview screenshots. HotSwan traces each @Preview function to find the composable it wraps, then extracts the KDoc description, parameter names, types, and default values.

hotSwanCompiler {
    preview {
        sdkModeEnabled.set(true)
        renderDelayMs.set(3000L)
    }
}

With SDK mode enabled, each card in the HTML catalog shows:

  • ✓Composable name chip: the actual composable being previewed (not the preview wrapper function)
  • ✓KDoc description: extracted from the composable's documentation comment
  • ✓Parameter table: name, type, default value, and @param descriptions
  • ✓Collapsible parameters: composables with more than 5 parameters show an expand/collapse toggle

This replaces the need for separate tools like Showkase or manual component documentation. Run captureAllPreviews in CI to automatically generate and publish your component catalog on every pull request.