Skip to content
xcross
Documentation menu

IDE integration

Set up VS Code or a JetBrains IDE to run, hot reload and debug a Flutter iOS app on a device with one command.

Both IDE integrations drive xcross flutter dap, a Debug Adapter Protocol server that routes launch, breakpoints, stepping, and hot reload requests to the same VM Service connection the CLI uses. Run one setup command per project, per IDE.

VS Code

xcross ide vscode

This writes:

  • .vscode/xcross_dap.dart - a shim spawned by the Dart-Code extension as dart xcross_dap.dart debug_adapter. It is always rewritten with the path of the xcross binary that ran the command, and the command warns if that is not an installed xcross (for example under dart run).
  • .vscode/launch.json - an xcross: iOS device entry marked "xcross": true, merged into any existing file rather than overwriting it.
  • .vscode/settings.json - dart.customFlutterDapPath pointed at .vscode/xcross_dap.dart, plus dart.promptToRunIfErrors: false, upserted the same way.

Press F5 to launch on a device; the Hot Reload / Restart buttons in the debug toolbar drive the same r/R commands as the CLI, and DevTools attaches over the same VM Service connection.

  • Works in any VS Code fork with the Dart-Code extension installed.
  • Launch configs without "xcross": true are handed to Flutter’s own debug adapter, so other Flutter launch configurations in the workspace keep working unchanged; the shim also forwards flutter test sessions to Flutter’s debug-adapter (which needs FLUTTER_ROOT to be set).
  • For multiple connected iPhones, add "args": ["--udid", "<UDID>"] to the xcross entry in launch.json; re-running xcross ide vscode preserves those args.
  • launch.json and settings.json are merged in place - existing keys are kept, and a second run that changes nothing reports the files as unchanged.
  • Run the installed xcross (the one on PATH), not a local checkout - the generated shim records that binary’s path.

JetBrains IDEA / Android Studio

xcross ide idea

This writes .run/xcross_ios_device.run.xml, a shared LSP4IJ Debug Adapter Protocol run configuration that starts xcross flutter dap over stdio.

  1. Install the LSP4IJ plugin.
  2. Debug the xcross: iOS device run configuration - not Flutter’s own Run button, which still calls flutter run and will fail off-macOS.

Breakpoints and stepping go through the DAP/VM Service path; Restart maps to hot restart, and the console still accepts r/R keypresses. An existing .run/xcross_ios_device.run.xml is never overwritten - if one is already there, xcross prints the XML for you to merge in by hand instead.

ImportantJetBrains’ own Flutter Run button does not know about xcross and will try to invoke flutter run directly, which does not work off-macOS. Always debug through the xcross: iOS device configuration.

The DAP server underneath

Both integrations are thin wrappers around:

xcross flutter dap

Importantxcross flutter dap is an internal command. It is hidden from xcross --help and is not intended to be run by hand - your IDE spawns it. It speaks DAP over stdio, so it suppresses xcross’s own banner to keep stdout clean for protocol frames.

xcross ide vscode re-resolves the xcross executable and rewrites the shim on every run, so reinstalling or upgrading xcross only needs a re-run of that command - no manual edits to .vscode/.

Next steps

  • CLI reference - every command and flag, including the xcross flutter run options F5 and Debug drive underneath.
  • Quick start - the same run from the terminal.
  • Troubleshooting - fix a stuck or failing IDE launch.
Edit on GitHubReport an issue
ESC