Preview, run & build
Watch it done (real recording)
Watch: Run app compiles the project and opens it in the phone frame, then hot-reloads.
FlutterGo runs your Android and iOS app right inside the browser. You don't need to install Flutter, Android Studio, or Xcode. The app compiles in the cloud and appears in a phone frame on your screen.
Two small control areas do all the work. The preview rail (on the right side of the preview) starts, reloads, and stops the running app. The project toolbar (above the preview) holds project-wide actions like Pub get, Clean, Share, GitHub, and Deploy.
This chapter explains every button, then walks you through the everyday loop: run the app, make a change, reload, and check the result.
What you need#
- Open a project that already has some generated code. If the preview says "Ask the agent to scaffold pubspec.yaml and lib/main.dart, then click Build", send one prompt first (for example "create the app skeleton").
- Nothing to install, the browser workflow works on its own.
- Optional: the desktop companion app (? menu, then Download desktop app) adds iOS Simulator and Android Emulator support with on-device hot reload.
Your workspace at a glance#
Everything lives on one screen: ① GitHub banner, ② conversation, ③ canvas, ④ preview rail, ⑤ project toolbar.
| Callout | Area | What happens there |
|---|---|---|
| ① | GitHub banner | Save the project to a private repo, see Save your code to GitHub. |
| ② | Conversation | Talk to the AI agent; every change happens through prompts. |
| ③ | Canvas & design files | Tabbed views of your screens; toggle Preview / Code. |
| ④ | Preview rail | Run, reload, analyze, and build, this chapter. |
| ⑤ | Project toolbar | Pub get, Clean, Share, GitHub, Deploy. |
The preview rail#
The right-hand rail controls the running app. Here is every button:
| Button | What it does | When to use it |
|---|---|---|
| Run app | Compiles your app and runs it in the phone frame in your browser. | First run, and after big changes. |
| Hot reload | Applies UI changes in ~1 second, keeping app state. | After most agent edits, fastest loop. |
| Hot restart | Restarts the app with fresh state. | When reload isn't enough (e.g. init logic changed). |
| Stop | Stops the running preview. | Before a clean rebuild. |
| Analyze | Runs flutter analyze and reports issues. | Checking project health (the agent usually auto-fixes). |
| Refresh | Reloads the preview frame. | If the frame looks stale. |
| Browser | Opens the running app in a separate browser tab. | Testing full-window behavior. |
| Build APK | Builds the Android APK and installs it on a connected device or emulator. | Trying the real Android build on hardware. |
Above the preview you can pick the Preview device frame (e.g. iPhone 16) and the zoom level (75%–125%). The agent also offers Run/Reload buttons inside its chat replies after changing code, so you rarely need to reach for the rail.
The project toolbar#
| Button | What it does |
|---|---|
| Pub get | Re-resolves packages after dependency changes. |
| Clean | Clears build artifacts, the classic first-aid step when a build behaves strangely. |
| Share | Creates a public link so you can open the running preview on other devices. |
| GitHub | Repo status, branch chip, and sync controls. |
| Deploy | Opens the deploy wizard, see Publishing to Google Play and Publishing to the App Store. |
How to do it#
Step 1, Run the app#
Click Run app in the preview rail. The status shows "Building Flutter web preview…" while the first compile runs. When it finishes, your app appears in the phone frame.
Tip: The first compile is the slowest. Every hot reload after it is fast, so keep the app running while you iterate.
Step 2, Make a change, then Hot reload#
Ask the agent for a change (for example "make the app bar purple"). When the change lands, click Hot reload. Your change appears in about a second and the app keeps its state, you stay on the same screen with the same data.
Step 3, Hot restart when reload is not enough#
Some changes (startup logic, dependency injection, main() changes) need a fresh start. Click Hot restart. The app restarts from its first screen with clean state.
Step 4, Check project health with Analyze#
Click Analyze. FlutterGo runs flutter analyze and shows results in the Analysis panel, "No issues found" when clean, or a Project issues list with error and warning counts. Any issue can be sent straight to the agent with Send to AI.
Success: You usually don't need this button, after each change the agent runs analyze itself and repairs what it finds.
Step 5, Read the logs when something looks wrong#
Click View logs to open the Preview debug logs panel. It shows the Build logs from the preview server and Runtime errors (browser console) from the running app. Use Copy logs to paste them anywhere, including into the chat.
Step 6, Test outside the phone frame#
Click Browser to open the running app in its own browser tab (full window, real scrolling, DevTools available with F12). If the embedded frame ever looks stale, click Refresh to reload just the frame.
Step 7, Build an APK for a real device#
With an Android device or emulator connected (desktop/local setup), click Build APK. The button shows "Building APK…", then "Installing…". On success the app opens on the device; on failure a one-click Fix with AI repair prompt appears.
Build APK compiles a debug build and installs it on a connected device.
Step 8, Share the running preview#
Click Share in the toolbar. FlutterGo creates a public link to the running web preview, the panel shows "Preview is live · Public" while sharing. Open the link on your phone or send it to a teammate. Click Stop sharing when you're done.
Important: Anyone with the share link can open your running preview. Stop sharing when you finish a session.
Devices and simulators#
iOS and Android simulator preview with on-device hot reload works through the desktop companion app (? menu, then Download desktop app). A Run on picker offers iOS Simulator, Android Emulator, and Web preview; the hint reads "Click Run app to launch on the selected simulator or emulator. Hot reload works on the device, not the web iframe." The browser workflow needs no install at all.
Show the code#
Every design file has a Show code / Preview toggle. The generated Dart is standard Flutter, read it, copy it, or continue in your own IDE; once synced to GitHub your project is a normal Flutter repository with no lock-in.
Common mistake: Editing code and forgetting compile errors. If the file has errors, running is blocked with "{count} compile errors, fix or send to AI before run". Use Fix compile errors or send the errors to the agent.
Troubleshooting#
Problem: The preview won't start or looks stuck. Possible causes: A stale preview process; broken build artifacts; a big change still compiling. Solution:
- Click Stop, then Run app again.
- Still stuck? Click Clean in the toolbar, then Pub get, then run again.
- If the agent just made a big change, give the first compile a moment, it's the slow one.
Problem: The preview builds fine but shows a blank (white or gray) screen. Possible causes: The browser is still loading; a runtime error inside the frame. Solution:
- Wait a few seconds, then click Refresh.
- Click View logs and expand Runtime errors (browser console).
- Or click Browser and press F12, then Console. Paste any red error into the chat.
- Click Rebuild if it persists.
Problem: Packages seem out of date after adding a dependency. Possible causes: Package resolution has not re-run. Solution:
- Click Pub get in the toolbar.
- Then Hot restart (or Run app if the app was stopped).
Problem: Build APK fails. Possible causes: Compile errors; no connected device or emulator. Solution:
- Click the Fix with AI prompt that appears on failure.
- Make sure an Android device or emulator is connected and visible.
- Run Analyze and clear any errors first.
FAQ#
Do I need to install Flutter on my computer? No. The browser preview compiles and runs everything for you. Installs are only needed if you want local simulators via the desktop app.
What is the difference between Hot reload and Hot restart? Hot reload applies UI changes and keeps your place in the app. Hot restart relaunches the app from the first screen with fresh state.
Why is the Run button disabled? Your project has compile errors. The rail shows "compile errors, fix or send to AI before run". Fix them (or let the agent fix them) first.
Can I test on my real phone? Yes, two ways: click Share and open the public preview link on your phone's browser, or connect an Android device and use Build APK.
Is there a cloud APK build without connecting a device? Not yet, cloud APK build is coming soon. Today Build APK installs onto a connected device or emulator.
Where does my code live? In your project, and, once connected, in your own private GitHub repository. See Save your code to GitHub.