Flutter Release

Preview release. macOS, Android and Web pipelines are verified on macOS (Apple Silicon). Windows MSI and Linux AppImage/DEB/RPM packaging are implemented and unit-tested but not yet verified on Windows and Linux hosts — please report issues.

Build, package and verify Flutter release artifacts from a graphical wizard in VS Code.

Select your platforms, architectures and installer formats, click Build Release, watch real progress, and get verified files in your output folder — without remembering flutter build flags, output paths, renaming steps or packaging commands.

Screenshots

Release wizard	Platforms & architectures
Review before building	Build progress

Contents

• Installation
• Usage
• Supported platforms and architectures
• Prerequisites
• Installer formats
• Changing the application name
• Changing the application icon
• Code signing and notarization
• Output directory structure
• Settings
• Security
• Troubleshooting
• Known limitations
• Development

Installation

From the Marketplace

Search for Flutter Release in the Extensions view, or run:

code --install-extension abdelazizaouiche0725.flutter-release

From a .vsix file

code --install-extension flutter-release-1.0.0.vsix

or in VS Code: Extensions view → … menu → Install from VSIX….

Requirements: VS Code 1.85 or newer, a Flutter SDK (detected automatically — see Flutter and Dart SDK detection), and the native toolchains for the platforms you build (see Prerequisites). No separate application or server is needed.

Usage

Open a folder containing a Flutter app. The Flutter Release icon appears in the activity bar.

Commands

Flutter and Dart SDK detection

No configuration is needed in most setups. The Flutter SDK is looked up in this order, and the first match wins:

1. flutterRelease.tools.flutterSdkPath (set by Select Flutter SDK)
2. The project's FVM SDK (.fvm/flutter_sdk, or the version pinned in .fvmrc / .fvm/fvm_config.json under ~/fvm/versions)
3. The Dart extension's dart.flutterSdkPath / dart.flutterSdkPaths
4. FLUTTER_ROOT
5. flutter on PATH (symlinks such as Homebrew's are resolved)
6. flutter on your login shell's PATH — VS Code started from the Dock or a desktop launcher may not see entries added in ~/.zshrc / ~/.bashrc
7. Standard install folders: ~/development/flutter, ~/flutter, ~/sdk/flutter, ~/fvm/default, puro, Homebrew Caskroom, /opt/flutter, snap, C:\src\flutter, %LOCALAPPDATA%\flutter, scoop, …

The Dart SDK bundled with that Flutter SDK is used. Without a Flutter SDK, a standalone Dart SDK is taken from flutterRelease.tools.dartSdkPath, dart.sdkPath, DART_SDK, PATH or Homebrew. The detected SDK, its version and where it came from are shown in the status bar (click it to switch), in the Release view and in Check Build Environment. If no SDK is found, the wizard opens a dialog offering Select Flutter SDK… or the Flutter install guide.

Popup windows

The Build & Package wizard, the Change App Icon wizard and the Build Progress view open as popups in their own floating window, which closes when the wizard finishes. Set flutterRelease.ui.openInNewWindow to false to open them as editor tabs instead. If VS Code does not finish loading a page inside its popup window (this occasionally happens with webviews in floating windows), Flutter Release reloads it and, as a last resort, moves it back into the main window so the wizard always stays usable.

The wizard

1. Project & name — shows the detected project, pubspec.yaml, Flutter/Dart versions and current app name. Enter the new app name (e.g. My Awesome App); a package-safe name (my_awesome_app) and folder name (MyAwesomeApp) are derived automatically. Preserve existing application configuration (default) uses the name only for output folders and installers. Untick it to apply the name to the native projects — the files that will change are listed live.
2. Platforms — Windows, macOS, Linux, Android, Web. Desktop platforms show an architecture selector that only enables architectures this host and Flutter SDK can really produce, with an explanation for the others. Android: APK, AAB, split per ABI. Web: base href.
3. Packaging — installer formats per platform. Formats whose tools are missing, or that cannot be produced on this host, are disabled with the reason and an alternative. Windows: product name, publisher, stable upgrade code, VC++ runtime bundling. macOS: Applications shortcut, signing identities, notarization profile and a Gatekeeper explanation. Linux: maintainer and desktop categories. Optional Dart obfuscation.
4. Output — main output directory (browse or type), optional separate directories for MSI / DMG+PKG / AppImage+DEB+RPM, platform/architecture sub-folders, and a live preview of the folder structure.
5. Review & build — application name, platforms, architectures, formats, locations, required tools, project changes, warnings and blocking errors. Build Release starts the real pipeline.

The Build Progress view shows one entry per target (e.g. Windows x64 — Building, macOS ARM64 — Waiting, Android AAB — Failed) with current operation, elapsed time, live log, output paths with sizes and verification results, error summary and buttons to cancel, retry failed targets, open the folder, copy error details and view the complete log.

Supported platforms and architectures

The extension never silently builds the host architecture when you selected another one: architectures are validated before the build, and every produced executable is inspected afterwards (PE, ELF and Mach-O headers). A mismatch fails the target with an explanation.

Prerequisites

Run Check Build Environment to see exactly what is missing. Flutter Release never installs system dependencies or edits your shell configuration; it shows commands you can copy.

Packaging tool prerequisites

Installer formats

Every installer is really generated by the native tool and verified afterwards — a process exiting successfully is not considered proof.

• MSI (Windows) — a WiX v4 source is generated from the release directory: per-machine install into Program Files, installation-directory dialog (WixUI_InstallDir, license page skipped), Start-menu shortcut, uninstall support through Apps & Features, product icon, and MajorUpgrade so a newer version replaces the older one. The upgrade code is generated once and stored in flutter_release.json at the project root — commit it, so every future MSI upgrades existing installations. The Visual C++ runtime DLLs are copied next to the executable (app-local deployment) when available. Verification: Windows Installer database signature plus ProductName, ProductVersion, Manufacturer and UpgradeCode read back through the Windows Installer API. MSI versions must be x.y.z within 255.255.65535.
• DMG (macOS) — compressed UDZO image with the app and an optional /Applications shortcut. Verified with hdiutil verify and by mounting it read-only and checking the app executable.
• PKG (macOS) — productbuild product archive installing into /Applications, optionally signed with a Developer ID Installer identity. Verified by expanding the archive and reading its bill of materials; signatures checked with pkgutil --check-signature.
• AppImage (Linux) — AppDir with AppRun, desktop entry, icons and the complete Flutter bundle, packed by appimagetool. Verified: ELF runtime, embedded squashfs payload, executable bit. GTK 3 must be present on the target system.
• DEB (Linux) — installs to /opt/<name>, /usr/bin/<name> symlink, desktop entry and hicolor icon; Depends: libgtk-3-0. Verified with dpkg-deb --info/--contents.
• RPM (Linux) — same layout; Requires: gtk3; macros in metadata are escaped. Verified with rpm -qlp.
• ZIP — portable archive of the release directory (macOS: ditto, preserving bundle metadata).

Android APK/AAB files are verified by reading the archive (manifest present, libapp.so per ABI); web builds by checking index.html and the compiled Dart output.

Changing the application name

Change App Name (or step 1 of the wizard):

1. Reads the project's actual native configuration — it does not assume a template.
2. Asks for the display name and the platforms.
3. Shows every file that would change, with a diff for each (uncheck files to skip them).
4. Creates a backup in .dart_tool/flutter_release/backups/ (ignored by git in Flutter projects).
5. Applies changes only after confirmation, and lists modified files (with Undo).

Only targeted values are edited — there is no repository-wide search-and-replace. Values are escaped per format (XML, plist, C/C++ wide strings, RC, HTML, JSON).

Identifiers are preserved (Android applicationId, iOS/macOS bundle identifiers, Linux APPLICATION_ID, signing, provisioning and entitlements). The command's Advanced option can change them separately, explaining the consequences: a new Android applicationId is a different app on Google Play; a new bundle identifier needs new provisioning and loses keychain/app data; the Kotlin namespace is left unchanged. The Dart package name can also be renamed (with package: import rewriting).

Changing the application icon

Change App Icon opens a wizard:

1. Select a PNG (1024 × 1024 recommended; at least 512 × 512).
2. The source is validated (valid PNG, square — or padded on request — resolution, transparency, artwork touching the edges, edge-to-edge opacity) and shown next to the current icon.
3. Select platforms (e.g. just Android + iOS, or all).
4. Preview generated icons (with launcher masks) and the full list of files that will be created, replaced or removed.
5. Update App Icon → confirmation → backup → write → every file is re-read and verified; on failure everything is rolled back.

Images are resampled with an area-averaging filter in premultiplied alpha, so edges stay clean. The extension's own branding is never applied to your app.

Code signing and notarization

macOS. Without configuration, apps are ad-hoc signed: they run on the build machine but Gatekeeper blocks them on other Macs. For distribution outside the App Store you need:

1. A Developer ID Application certificate → flutterRelease.macos.signingIdentity (the wizard's packaging step). Frameworks and the app are signed with the hardened runtime and macos/Runner/Release.entitlements.
2. For PKG: a Developer ID Installer certificate → flutterRelease.macos.installerSigningIdentity.
3. Notarization: store credentials once in the keychain — xcrun notarytool store-credentials "my-profile" --apple-id you@example.com --team-id TEAMID — and set flutterRelease.macos.notaryKeychainProfile to my-profile. DMGs/PKGs are submitted with notarytool --wait and stapled. Flutter Release never sees your Apple ID password.

The build summary and progress view warn whenever an artifact is unsigned or not notarized.

Android. Flutter's template signs release builds with the debug key. The environment check and the build flag this; configure a release keystore as described in the Flutter documentation and keep key.properties out of version control.

Windows. MSI signing is not performed automatically; sign with signtool after building if required.

Output directory structure

Default root: ~/FlutterRelease (configurable; ~ and ${workspaceFolder} are supported). The project's build/ directory is rejected because flutter clean deletes it.

FlutterRelease/
└── MyAwesomeApp/
    ├── windows/
    │   └── x64/
    │       ├── release/        # portable app folder
    │       └── installer/      # MyAwesomeApp-1.2.3-windows-x64.msi / .zip
    ├── macos/
    │   └── arm64/
    │       ├── release/        # My Awesome App.app
    │       └── installer/      # .dmg / .pkg / .zip
    ├── linux/
    │   └── x64/
    │       ├── release/
    │       └── installer/      # .AppImage / .deb / .rpm / .zip
    ├── android/
    │   ├── app-release.apk
    │   └── app-release.aab
    ├── web/
    │   └── build/
    ├── debug-symbols/          # when obfuscation is enabled
    └── logs/                   # one redacted log per target

Disable Organize output for a flat layout, or choose separate installer directories per platform. Existing releases are never overwritten silently: you are asked to overwrite the targets being built or to use a versioned directory (MyAwesomeApp-1.2.3+4, then -2, -3, …). With flutterRelease.confirmBeforeOverwrite disabled, a versioned directory is always used.

Settings

Tool paths and signing identities are machine-overridable, so they can live in user settings rather than the repository.

Security

• Commands are executed with argument arrays (child_process.spawn, shell: false). User input is never interpolated into shell command strings. The only exception is flutter.bat on Windows, which must run through cmd.exe: every argument is quoted and arguments containing ", %, !, ^ or line breaks are rejected.
• Logs are redacted (password/token/secret flags, key=value secrets, secret-looking environment variables).
• No secrets are stored by the extension. Notarization uses a keychain profile; Android signing stays in your Gradle configuration.
• In untrusted workspaces, builds require explicit confirmation (they execute Gradle, CMake and Xcode scripts from the project).
• Project files are only modified after a preview and confirmation, with a backup. Restore uses only the files recorded in the backup manifest and refuses paths outside the project.
• Cancellation terminates the whole process tree; cleanup removes only this session's temporary directory and partial files created by the cancelled step — never existing releases or your files.

Troubleshooting

Known limitations

• Desktop builds require the matching OS. Windows targets only the host architecture. Linux cross-compilation needs a sysroot and toolchain you provide.
• Android flavors and iOS/IPA builds are not supported.
• AppImage/DEB/RPM do not bundle GTK 3; it must be installed on target systems. AppImages for another architecture cannot be created on this host.
• MSI packages are not code-signed automatically; the license page is skipped. WiX v4–v6 command line is supported.
• macOS DMG volumes use the default volume icon and window layout.
• Localized Android values-xx/strings.xml labels are not changed.
• Only one build session runs at a time per VS Code window.
• VS Code does not let extensions size popup windows or make them modal; the window can be resized and moved freely.
• Verified platforms: the full pipeline (macOS universal + ARM64-thinned app, DMG, PKG, ZIP, Android APK/AAB, Web) was exercised on macOS 14 (Apple Silicon) with Flutter 3.47. Windows MSI and Linux AppImage/DEB/RPM packaging are implemented and unit-tested (generated WiX source, control files, spec files, command lines), but must be validated on Windows and Linux hosts with their toolchains before relying on them.

Development

npm install
npm run compile          # TypeScript → out/
npm run bundle:dev       # esbuild → dist/extension.js
npm run lint             # ESLint
npm run format:check     # Prettier
npm run test:unit        # Mocha unit tests (external processes mocked)
npm run test:integration # VS Code Extension Development Host tests (downloads VS Code; set VSCODE_EXECUTABLE to reuse one)

Set FLUTTER_RELEASE_E2E=0 to skip the real flutter build web in the integration suite.

Debugging: open this folder in VS Code and run the Run Extension (sample project) launch configuration (F5). It bundles the extension and opens test-fixtures/sample_app in an Extension Development Host.

Packaging a .vsix:

npm run package

This runs the production esbuild bundle (vscode:prepublish) and produces flutter-release-1.0.0.vsix (≈160 KB) with @vscode/vsce. Publish a new version with npm run publish after npx @vscode/vsce login abdelazizaouiche0725.

Architecture

src/
  extension.ts              activation, command registration
  config.ts                 typed VS Code settings
  releaseContext.ts         shared state (output channel, session, caches, trust)
  commands/                 buildRelease, changeAppName, project commands
  ui/                       ReleaseWizardPanel, IconWizardPanel, ProgressPanel, EnvironmentPanel, tree view
  services/                 projectDetector, flutterService, architectureService, environmentChecker,
                            appNameService, appIconService, backupService, outputService,
                            installerService, configValidator, buildOrchestrator, toolLocator
  packaging/                windowsMsi, macosApp, macosDmg, macosPkg, linuxAppImage, linuxDeb, linuxRpm
  models/                   buildConfiguration, buildResult, projectInfo
  utils/                    processRunner, pathValidation, logging, platformSupport, image, binaryInspect, fsUtils
  test/                     unit/ (Mocha), integration/ (@vscode/test-electron)
media/                      webview scripts/styles, extension icons
test-fixtures/sample_app    Flutter template project used by tests

Services, packaging and utilities do not depend on the VS Code API and are tested directly with mocked processes.