Migrating native screens

Some screens are worth changing without an app release: the update-required screen you need on the day you cannot ship, an onboarding step, a rate-us or notifications prompt, an announcement, an offer. Each of those can be a framework surface shown through a placement, like a paywall. superwall migrate --screen takes the native screen you have today and does the deterministic half of that move; a coding agent rebuilds the pages; you review the result in the studio next to a screenshot of the original; then you wire the app.

Start from the screen

In your app's root, with the file that draws the screen:

superwall migrate --screen App/UpdateRequiredView.swift

Leave the path off and the CLI scans the app for likely candidates (files named or shaped like update, onboarding, paywall, rate-us, permission or announcement screens) and asks which one. SwiftUI and UIKit (.swift), Jetpack Compose and Android Views (.kt), React Native (.tsx) and Flutter (.dart) files are read.

The scan reads one file and writes, into the project it finds (or a new superwall/ directory):

• paywalls/<slug>/config.ts with the screen's name and, if the source referenced store product identifiers, one product slot per identifier. Confirm those exist on the dashboard; a push refuses unknown products.
• paywalls/<slug>/MIGRATION.md, the brief: the source path and framework, every user-visible string with its dynamic values, the image and font assets and system symbols it uses, its links, and each action it performs mapped to the framework hook that replaces it (an App Store link becomes useActions().openUrl, a review request requestStoreReview, a notification prompt requestPermission("notification"), a dismiss close).
• An origins entry in superwall.lock naming the source file, so superwall migrate --screen can pick the rebuild up later.

The scan is a starting inventory, not a parser of your app. For a UIKit controller it also reads the view, view model and storyboard scene it references; for an Android Activity or Fragment it reads the layout XML and resolves R.string and @string/ references from strings.xml. Anything else that lives in a view model or a theme file is left to the agent, which follows the source's imports.

Capture the original

The studio cannot render a native screen, so the comparison uses a screenshot. With the screen open in a booted iOS simulator, the CLI offers to capture it; pass one yourself with --screenshot path.png (an Android emulator capture works the same way). It is saved as paywalls/<slug>/original.png, and the studio's Compare menu offers it as Original, opening on it directly when the CLI starts the studio for you. Without a screenshot there is no Original entry; keep the app running in the simulator beside the studio instead.

Rebuild the pages

After the scaffold the CLI asks whether to run the rebuild now with the coding agent it finds (Claude Code or Codex), copy the prompt for an agent you drive yourself, or stop.

Running it with your agent hands it the brief and the rebuild playbook from the superwall-framework skill (references/migrate-from-native.md) plus its native/ file for the source framework, headless, in the superwall/ directory. The order of work is fixed: read the source and everything it imports, lift the design tokens, rebuild each state as a page with the framework's hooks, every string through messages/en.ts and t(), assets copied into assets/, typecheck green. It writes only inside paywalls/<slug>/: it never edits the app, never adds register() calls, and cannot push, promote or touch campaigns.

superwall migrate --screen <path> --skill prints that prompt to stdout for a screen already in the project.

Review

superwall dev

Open the screen, pick Compare › Original, and check every state in both schemes and on the devices the app supports. Anything that does not match is a normal edit in paywalls/<slug>/; the studio reloads live. MIGRATION.md is yours to delete once you are done with it.

Wire the app

Push when it is right, then make the app present the surface where it used to present the native screen. The brief names the placement, derived from the screen's name:

// before
if needsUpdate { present(UpdateRequiredViewController(), animated: true) }

// after
if needsUpdate { Superwall.shared.register(placement: "update_required") }

Registering a placement is the same in every SDK; the feature-gating pages for iOS, Android, Expo and React Native and Flutter are the reference, and the superwall skill's workflows/placements/ playbook (superwall integrate --skill prints it) is what your agent follows. Create a campaign for that placement on the dashboard and point it at the pushed surface; superwall integrate and the superwall skill's workflows/dashboard/ playbook do this. A screen the user must not dismiss is a gated surface: the campaign's paywall is set to gated, and the feature closure only runs when the user has been let through, so keep the app's own hard block until the surface is live. Delete the native screen once the campaign is verified on a device.

The framework file the agent read (references/native/ios.md, android.md, react-native.md or flutter.md in the superwall-framework skill) has the same table for every source construct and every wiring pattern, so ask it to do the wiring with you.

What does not migrate

• Anything the screen did after itself (routing, refreshing data): the surface closes and the app's placement handler continues.
• Native-only pieces: a share sheet, a camera view, a settings deep link the SDK cannot open. The agent lists them as not carried over.
• Data the screen fetched itself. Pass it as placement params, or set it as user attributes before register(), and read it in the surface with useVariables().

See also Migrating from the editor for the same workflow starting from a dashboard paywall.