Markdown

Server-driven UI

Change what a screen looks like (its text, order, sections, tables, lists, buttons) without a store release. Your app ships the building blocks once; Stacklift sends a layout that arranges them. The layout is data, not code, so it works for native SwiftUI, Jetpack Compose, Flutter and React Native apps without breaking App Store or Google Play rules.

What you can change over the air:

  • Text and titles, including values from your data ("Hi {{user.name}}")
  • The order of sections and components
  • Lists and tables: which data they show, their columns, how each row looks
  • Show or hide anything with a condition ("visible": "{{user.isPro}}")
  • Buttons: their label, style and what they do (open a screen, open a link, or send an event your code handles)
  • Your own components (ProductCard, ...), placed and configured by the layout

What still needs a store release: a brand-new kind of component, a new native capability (camera, a new permission, a new SDK), or new logic (use scripts for rules). After that one release, the new piece can be arranged over the air like everything else.

How it works

  1. You wrap a screen once and keep your current screen as the fallback.
  2. A layout ships inside the app, so the first launch and offline launches look right.
  3. You publish a new layout with the CLI. The server validates it before signing it.
  4. The app downloads it in the background, verifies the signature, and applies it the next time it opens (never mid-session).
  5. If a launch with the new layout never reaches confirmLaunch() twice in a row, the app rolls back to the last good layout. A layout the installed app cannot draw (for example one using a component from a newer format) is never applied.
bash
stacklift ui validate home.json          # the same checks the server runs
stacklift release create --version 1.1.0 --runtime-version 1 --artifact ios:ui-layout:./home.json --channel production

A release can carry a layout and a script for the same platform; each SDK asks for its own kind.

The dashboard editor

Open a project and choose Screens (shown for stacks that support server-driven UI). The editor opens the layout a channel serves now, or the newest one you published.

  • Outline: the screen's components as a tree. Drag to reorder or to move something into a column, row, section or card. ⌥↑/⌥↓ move, ⌘D duplicates, ⌫ deletes, ⌘Z/⇧⌘Z undo and redo.
  • Preview: the screen in a phone frame, light or dark, drawn with the same resolver as the apps. Click anything to select it. Buttons show what they would do. The app's own fonts, colours and custom components appear only on a device.
  • Properties: a form for the selected component (text, style, list binding, table columns, button action, visibility). With nothing selected: the screen's title and ID.
  • Sample data: example values for the preview. *Fill in missing values* creates them from the bindings the screen uses. Sample data is never published.
  • JSON: the whole document as text, for anything the forms do not cover.
  • Checks: the same validation the server runs before signing. Publishing is disabled while there are errors; click an issue to jump to the component.

Publish creates a release with the layout for the platforms you choose. The server validates and signs it like any artifact, and nothing reaches apps until you deploy the release to a channel. Unpublished edits are kept in your browser (only there) until you publish or discard them.

JSON downloads the document and Export code ejects the current screen to SwiftUI or Flutter source, the same output as stacklift ui export. The editor uses only the public endpoints (GET /projects/:project/layouts and GET /projects/:project/layouts/:artifact) and the normal release API.

The layout format (stacklift-ui/1)

json
{
  "format": "stacklift-ui/1",
  "screens": {
    "home": {
      "body": {
        "type": "column",
        "children": [
          { "type": "text", "text": "Hi {{user.name}}", "style": "title" },
          { "type": "list", "items": "{{products}}", "item": { "type": "card", "children": [{ "type": "text", "text": "{{item.name}}: ${{item.price}}" }] } },
          { "type": "button", "title": "Upgrade", "action": { "type": "navigate", "to": "/upgrade" } }
        ]
      }
    }
  }
}

Components: column, row, section, card, text, image, button, list, table, divider, spacer, custom. Bindings are {{path.to.value}}; a string that is exactly one binding keeps its type (a list, a number), anywhere else it becomes text. Inside a list, item and index are available. Limits: 32 levels deep, 2000 components, 500 list items, 512 KB.

The format is open and documented: the JSON Schema is in `packages/ui-schema/schema/stacklift-ui-1.schema.json` and the reference resolver is in packages/ui-schema. The TypeScript, Swift and Dart resolvers are all checked against the same fixtures, so a layout looks the same everywhere.

SwiftUI

swift
import Stacklift

let layouts = StackliftLayouts(client: client, options: .init(runtimeVersion: "1", currentVersion: appVersion), bundled: bundledLayoutData)
layouts.prepareLaunch()                                   // early in launch

StackliftScreen("home", layouts: layouts, data: try JSONValue.from(model),
                components: ["ProductCard": { props in AnyView(ProductCard(props)) }],
                onAction: { action in router.handle(action) }) {
    HomeView()                                            // your current screen: shown whenever the layout cannot be drawn
}

layouts.confirmLaunch()                                   // once the app is healthy
Task { _ = try? await layouts.stage(); await layouts.flushEvents() }   // background: download for the next launch

Flutter

dart
import 'package:stacklift_flutter_ui/stacklift_flutter_ui.dart';

final layouts = StackliftLayouts(client: client, directory: dir, runtimeVersion: '1', deviceId: deviceId, platform: currentStackliftPlatform(),
    bundled: await rootBundle.loadString('assets/home-layout.json'));
layouts.prepareLaunch();

StackliftScreen(
  screen: 'home',
  layouts: layouts,
  data: {'user': user.toJson(), 'products': [for (final p in products) p.toJson()]},
  components: {'ProductCard': (props) => ProductCard.fromJson(props)},
  onAction: (action) => router.handle(action),
  fallback: (context) => const HomeScreen(),              // your current screen
);

packages/sdk-dart holds the format, verification and lifecycle (plain Dart); packages/sdk-flutter-ui holds the Flutter widget.

The Flutter renderer is the same code on Android: examples/flutter-scripts was verified on an Android 17 emulator too (see its README for two Android build settings).

Jetpack Compose (Android)

kotlin
import dev.stacklift.android.*

val layouts = StackliftLayouts(client, StackliftAndroid.options(context, "layouts", runtimeVersion = "1"),
    bundled = assets.open("home-layout.json").use { it.readBytes().toString(Charsets.UTF_8) })
layouts.prepareLaunch()                                   // early in launch

setContent {
    StackliftScreen("home", layouts, data = mapOf("user" to mapOf("name" to user.name)),
        components = mapOf("ProductCard" to { props -> ProductCard(props) }),
        onAction = { action -> router.handle(action) }) {
        HomeScreen()                                      // your current screen
    }
}

layouts.confirmLaunch()                                   // once the app is healthy
lifecycleScope.launch { layouts.stage(); layouts.flushEvents() }   // background: download for the next launch

packages/sdk-android draws with Material 3 and your MaterialTheme. Text styles map to Material type (largeTitle → headlineLarge, title → headlineMedium, headline → titleMedium, body → bodyLarge, caption → bodySmall); colours map to the colour scheme (accent → primary, secondary → onSurfaceVariant, danger → error). Rows follow the same rule as SwiftUI and Flutter: with a flexible spacer, what follows it sits at the trailing edge. StackliftLayouts.offline(bundled) and use(json) work without Stacklift, as on the other platforms. See the SDK README for requirements: signature checks need Android 13 (API 33) or a registered Ed25519 provider.

Home Screen widgets (WidgetKit)

Not built yet. StackliftScreen is made for app screens; widgets need their own renderer. This section says what will and will not be possible, so you can plan for it.

Possible over the air once the widget renderer exists:

  • Edit a widget's design: its text, order, which information shows, sizes and colours from your palette.
  • Remove a design. Widgets already placed on someone's Home Screen fall back to a design built into the app.
  • Add a new design built from pieces the app already has (text, rows, your own custom views). If the app has one widget whose "Widget Type" is chosen in Edit Widget, that list can come from downloaded data, so a new design appears as a new choice without a store release.

Still needs a store release:

  • A new entry in the Add Widget gallery, a new size family or a new configuration screen. Apple compiles these into the widget extension.
  • Data the widget does not read today (a new permission or API). A layout only shows data the app already provides.
  • New widget buttons. Interactive widgets run App Intents compiled into the app; a layout can place existing ones, not create new ones.
  • A visual element the app does not have yet. Ship the view once, and layouts can use it from then on.

How it will work: the app downloads and verifies the layout, saves it in the App Group shared with the widget extension, and asks WidgetKit to reload. The widget never goes online itself. A new design therefore shows after the app next opens or gets background time, not instantly. The renderer has to draw a static snapshot: no scrolling, no images loaded from the web, buttons only as App Intents, and the Lock Screen and StandBy rendering modes.

Troubleshooting

  • Publish is disabled in the editor. Checks found an error. Click it in the Checks list to jump to the component.
  • The app still shows the old screen. Layouts apply on the next launch: open the app once (it downloads), close it, open it again. Also check the release is deployed to the channel the app uses, with the app's runtime version, and that the app asks for kind: ui-layout (the SDK's StackliftLayouts does).
  • The app shows the fallback screen. The layout uses something the installed app cannot draw (a component from a newer format, or a custom component the app did not register), or the screen ID does not match the one the app asks for. The SDK's onError callback says which.
  • The app went back to an older layout. Two launches with the new layout never reached confirmLaunch(), so the SDK rolled back and will not retry that release. Fix the cause and publish a new version.
  • The preview looks a little different from the device. The preview uses the same layout rules but the browser's drawing; your app's fonts, colours and custom components appear only on a device.
  • Android: update checks time out against a local server. Apps that target Android 17 (API 37) cannot reach private addresses such as the emulator's 10.0.2.2 without the ACCESS_LOCAL_NETWORK permission. Use adb reverse tcp:4100 tcp:4100 and http://localhost:4100 while developing; a production server on the internet is not affected.
  • Upload failed with "Size mismatch: declared …, stored 0". Fixed in the API: the upload receiver no longer parses request bodies. Update your Stacklift server.

React Native

tsx
import { StackliftScreen } from '@stacklift/react-native';

<StackliftScreen screen="home" bundled={require('./home-layout.json')} data={{ user, products }}
  components={{ ProductCard: (p) => <ProductCard {...p} /> }} onAction={(a) => router.handle(a)}
  fallback={<HomeScreen />} />

The React Native renderer uses the reference resolver itself (@stacklift/ui-schema), so it cannot drift from the other platforms. The layout is delivered and applied on the next launch by the same native code that handles code push (see OTA for every stack), and Stacklift.confirmLaunch() confirms both. Default colours follow iOS system colours and the phone's light or dark mode; pass colorScheme="light" if your app is light-only, theme to use your own colours, and images for images that ship in the app.

React Native apps can also change any JavaScript with code push, so use layouts for what non-developers should change from the dashboard editor, and code push for everything else.

Leaving Stacklift (no lock-in)

  • Your app keeps working. Every screen has your own fallback, and the layout bundled in the app renders without any server. If Stacklift is unreachable, removed, or the account is closed, nothing breaks.
  • Host layouts anywhere. StackliftLayouts(bundled:) (Swift) or StackliftLayouts.offline() (Dart) plus use(...) renders a layout you fetch from your own server or CDN. StackliftScreen also takes a plain document.
  • Eject to code. Turn any screen into ordinary SwiftUI or Flutter source with no Stacklift dependency:
bash
stacklift ui export home.json --screen home --to swiftui -o HomeScreen.swift
stacklift ui export home.json --screen home --to flutter -o home_screen.dart

The generated file includes the few helper functions the bindings need. Replace the data lookups with your own model properties and remove the SDK. A test renders the ejected Flutter widget next to the live renderer and checks they show exactly the same text.

Staying within the store rules

Apple App Review Guideline 2.5.2 and Google Play policy forbid downloading code that adds or changes functionality. A layout contains no code: it arranges components your reviewed app already has. Use it to change how existing features look and are arranged, not to switch on hidden features after review.

Status

Built and tested: the format, validator and reference resolver; server validation before signing; the CLI (ui validate, ui export, releases); SwiftUI, Jetpack Compose, Flutter and React Native renderers; next-launch apply, rollback and reporting; eject to SwiftUI and Flutter; the dashboard editor (outline, live preview, properties, sample data, JSON, checks, publish, export). Both demo apps (examples/swift-scripts, examples/flutter-scripts) changed their home screen over the air on the iOS 26 simulator against a live server. On a Pixel 6 Pro emulator (Android 17), examples/android-scripts (Compose) and examples/flutter-scripts did the same, and the Compose demo also ran on a physical HONOR ELI-NX9 (Android 16), and the Compose renderer has 6 rendering tests on the emulator plus the 17 shared conformance cases. The editor was checked in a browser: edit, validate, publish, deploy, reopen.

Not yet: a widget (WidgetKit) renderer, .NET MAUI and Unity renderers, eject to Compose or React Native code (ui export writes SwiftUI or Flutter), and a run on a physical iPhone. Drafts live in one browser, so two people cannot share an unpublished draft.