Development workflow
Patchwing lets you ship Dart code updates to your Flutter apps instantly, without waiting for app store review. This guide walks you through the whole loop on a fresh computer: install the CLI, register, create an app, release a baseline, then push a patch and watch the already-installed app update itself.
1. Before you begin
Section titled “1. Before you begin”Install Git 2.25.1 or newer. For Android development, install Android Studio and use its SDK Manager to install Android SDK Platform 36, SDK Build-Tools, Command-line Tools, Platform-Tools and NDK 28.2.13676358. Prepare an emulator or a phone with USB debugging enabled. See the official Android setup for details.
The project template uses Gradle 9.1.0 and AGP 9.0.1, and the build JVM must be Java 17 or newer — the JDK bundled with Android Studio satisfies this.
For everyday editing and debugging, install the public Flutter SDK following the official guide and add its bin directory to your PATH, then check the Android toolchain:
On Windows, use Windows 11 x64 with PowerShell 5.1 or newer (no WSL). Run the following once in an administrator PowerShell and confirm it prints true, then close that window and continue as your normal user. Android builds do not need the Visual Studio C++ desktop tools.
To build for iOS, use an Apple Silicon Mac with full Xcode and the iOS platform installed, a valid signing team and provisioning profile, Developer Mode enabled on the iPhone, and CocoaPods if your plugins need it. See the official iOS setup.
2. Create your account
Section titled “2. Create your account”Open the registration page, verify your email with a code and set a password. You will use this email and password to sign in to the console, and an email code to reset the password if you forget it. No organization setup is required.
3. Install Patchwing
Section titled “3. Install Patchwing”After installing, close and reopen your terminal so the updated PATH takes effect, then verify the installation and sign in:
pw login opens your browser: confirm the authorization with the same email and its verification code, and allow the localhost callback. pw doctor reviews both your Android toolchain and the Patchwing-specific project configuration — follow its hints if something is missing.
4. Create a new app
Section titled “4. Create a new app”Run this from a writable workspace (for example C:\pw-projects on Windows). It creates a Flutter app and initializes Patchwing: the app_id in patchwing.yaml is the app you will see in the console. To add Patchwing to an existing Flutter project, run pw init from its root instead.
For this walkthrough, set the version in pubspec.yaml to 1.0.0+1, keep the generated counter app, and change the home page title in lib/main.dart to BASE. Commit the source and pubspec.lock to Git, then run pw doctor in the project and follow its hints (for example the INTERNET permission).
5. Release and install the baseline
Section titled “5. Release and install the baseline”A release registers the baseline your users install. On Android it produces an AAB by default; get-apks generates installable APKs from it. Start your emulator or connect your phone, check that it shows up, and install the APK:
With multiple devices attached, pass the device id with adb -s. If adb is not found, add the Android SDK Platform-Tools directory to your PATH.
For iOS, open ios/Runner.xcworkspace in Xcode first, set the Runner signing team and a unique bundle identifier, then install the signed IPA reported by pw release via Xcode Devices and Simulators.
Open the installed app: it shows BASE, and tapping + increments the counter by 1. When you later publish to stores, configure your own release signing and submit the artifact produced by pw release.
6. Publish a Dart patch
Section titled “6. Publish a Dart patch”Keep the version at 1.0.0+1. In lib/main.dart change the title from BASE to PATCHED and change _counter++ to _counter += 3, update the generated widget test to expect 3 after one tap, commit, then publish the patch to the stable track:
For your own app, pass the release version you actually registered and keep the same flavor, entrypoint and dart-defines as the baseline. Dart files, functions and top-level variables can be added or changed freely; changes to native code, plugin native implementations or bundled assets need a new baseline release.
7. Verify the update and roll back
Section titled “7. Verify the update and roll back”Keep the installed app online: it checks for updates and downloads the patch in the background. A finished patch activates on the next full start of the app — it does not hot-swap the running session. If the download starts while you are watching, give it a moment and cold-start the app again (fully close it, then reopen).
Reopen the app: it now shows PATCHED, and tapping + increments by 3 — the package version and signature are unchanged. To undo a patch, open the app and its release in the console and roll the patch back; the installed app picks up the rollback after a cold start and returns to BASE with increments of 1.
Troubleshooting and next steps
Section titled “Troubleshooting and next steps”If a step fails, stay on it and read the command output — network errors can simply be retried, and anything persistent is worth sending to contact@patchwing.net with the full output. For day-to-day work, see the Release and Patch references.