Blog / Product
Introduction to a new era of Flutter development
Zapbird runs your Flutter app on a real phone the moment you save, with no emulator, no native build and no cloud account. What it is, how it is built, and how a day of development changes.
Flutter gave teams one codebase for every screen. The loop around that codebase, though, has barely moved: start an emulator, wait for a native build, set up signing, and only then find out how the app really feels in a hand. Zapbird is our attempt to remove that weight. It runs your Flutter project on the phone you already own, the moment you save a file, and it does it entirely on your own network.
This post is the long introduction. It explains what Zapbird is, how the pieces fit together, what a normal day of development looks like, and where its limits are. Where a topic has its own page, we link to the documentation so you can go deeper.
The problem with the usual loop
A typical Flutter session on a device has a lot of furniture around it. You boot an emulator or plug in a cable. You wait while a native toolchain builds your app. You manage signing identities just to try an idea on hardware. Each step is reasonable alone, but together they add friction to the one thing you came to do: change code and look at the result.
The emulator also is not the phone. Touch, scrolling, fonts, haptics and performance feel different on a real device, and the sooner you see your work there, the sooner you catch what an emulator hides.
What Zapbird is
Zapbird is instant mobile infrastructure for Flutter. It has three parts that work together:
- The zapbird command on your computer. It watches your project, compiles it and serves it to your phone. See the command reference.
- The runner SDK, the compiler files that match one build of the runner on your phone. It is installed and switched with the sdk command.
- The Zapbird runner, an app on your phone that pairs with your computer and runs your project.
You keep your editor, your packages and the way you already write Flutter. Zapbird changes where the app runs and how quickly a change reaches it, not how you build it.
Architecture at a glance
Zapbird has two ends and a network between them. The server lives on your computer, next to your project. The runner lives on your phone. They talk directly, over TLS, on your local network or over Tailscale if you turn it on. There is no cloud service in the middle and no account to create.
Read from top to bottom, the layers are: your project, then zapbird (file watcher, compiler, TLS server, pairing, doctor and the SDK manager), then the runner SDK, then your network, then the runner on the phone. The architecture page draws this as a diagram and explains what each layer is responsible for.
What happens when you save
The loop from keystroke to screen is short, and each step is simple:
- The file watcher in zapbird sees that you saved.
- The compiler turns your project into bytecode, using the runner SDK.
- zapbird offers the new code to your paired phone over the TLS connection.
- The runner downloads the code and checks it before using it.
- The runner applies the change in place and keeps your app state for the edits where that is possible.
When a change cannot be applied while keeping state, the app restarts from its first screen. That is the honest outcome: a half-applied change is worse than a restart. How Zapbird works goes through the same steps with the reasons behind them.
A day of development
Start inside your project. If it is new, the create command makes one. Then check your setup and start the server:
$ zapbird doctor
$ zapbird startScan the QR code with the runner and approve the project once. From then on, every save shows on the device. The quick start takes you through the first run, and Connect your phone covers the other ways to pair.
Errors are first-class. When your code does not compile or throws, the error appears on the phone with the file and line, and tapping a line opens it in your editor. The same message prints in your terminal with keys, tokens and passwords hidden. A compile error never replaces the last working version, so your app keeps running while you fix it.
You choose how it runs. With a runner SDK installed, zapbird start uses bytecode mode, where every save reaches the phone by itself. Without one it serves kernel mode, which runs full Flutter and needs nothing extra; there you type r to reload and R to restart. The development guide lists the keys, and Work with another project shows how to point at a different folder, pass --dart-define values and pick an SDK.
Keeping your project in step with the runner
The runner contains a fixed set of packages at fixed versions, so a project that asks for different ones will not agree with it. Zapbird does not leave you to find that out the hard way. The doctor command checks the network address, the project, Flutter, the SDK, your package versions and the keys in your project, and says how to fix each problem. zapbird doctor --fix sets the package versions for you and prints every change.
Zapbird is built for Flutter 3.41.x (Dart 3.11), so stay on that version until the docs say otherwise. When the runner on your phone updates, zapbird sdk upgrade fetches the matching SDK. See Prepare your workspace for the full routine.
Security and data
Zapbird has no cloud account and sends no analytics. The server makes a new TLS certificate every time it starts, and the QR code carries it, so the phone trusts only your server and another computer on the Wi-Fi cannot pose as yours. The QR code also carries a secret, so treat it like a password: it works for 24 hours by default, or once with --single-use-qr.
Your phone receives compiled bytecode and your assets, not your source files, unless you deliberately turn on phone editing with --allow-phone-edit. A project that holds server-side keys, such as a Stripe secret, is refused before it is sent. The details are on the security page, and Data and network lists exactly what runs where, what travels and what is stored.
What the runner can do for your app
Native code cannot be downloaded onto a phone, so the packages that use it are built into the runner. Your project can use those packages with no native setup, such as the camera, location, notifications and Bluetooth. The native APIs reference lists every package and its version. A package that is not on that list needs a store build.
From development to the stores
Zapbird is for the development loop, and it does not pretend to replace the store build. When you are ready to ship, your own app needs its permissions written into Info.plist and AndroidManifest.xml. zapbird.yaml keeps those permissions in one place, with your reasons in your own words, and zapbird config apply writes them. zapbird release check then looks for what the stores refuse, such as a missing version or an app id that still starts with com.example. The store builds guide walks through it.
Where Zapbird is honest about its limits
- You still need Flutter itself, at the supported version.
- The phone and the computer need to reach each other: the same network, or Tailscale on both.
- Packages with native code must be among the ones built into the runner; others need a store build.
- Some edits restart the app instead of keeping its state.
If something does not work, start with the troubleshooting page, which lists symptoms and fixes, and the FAQ for the quick answers.
Try it today
Install the command and the SDK, scan one QR code, and watch your first save land on your phone. The install guide covers Mac and Windows, and the quick start takes a few minutes. If you get stuck, write to support and include the output of zapbird doctor.
This is the first post on the Zapbird blog. Next we will go deeper into pairing, the runner SDK and the store build tools. If there is a part of Zapbird you would like explained, tell us.