wailsapp · leaanthony · Jul 6, 2026 · Jul 6, 2026 · Jul 6, 2026 · Jul 6, 2026
diff --git a/IMPLEMENTATION.md b/IMPLEMENTATION.md
@@ -70,6 +70,16 @@ This document tracks the implementation of WebKitGTK 6.0 (GTK4) support for Wail
 
 **Decision**: No changes needed - system tray is already GTK-agnostic.
 
+### Decision 6: Go 1.25 Minimum for v3 Migration (2026-08-09)
+**Context**: Wails v3 requires Go 1.25+, and the migration command generates a
+new v3 module for the user's project.
+
+**Decision**: `wails3 migrate` raises generated modules to `go 1.25` when the
+source project declares an older version.
+
+**Rationale**: Migrated projects must declare the same minimum toolchain as the
+v3 project and its released dependencies so the generated module is buildable.
+
 ## Implementation Progress
 
 ### Phase 1: Build Infrastructure ✅ COMPLETE

diff --git a/docs/src/content/docs/blog/2026-08-02-wails-v3-beta.md b/docs/src/content/docs/blog/2026-08-02-wails-v3-beta.md
@@ -134,9 +134,11 @@ expect every v2 project to convert without review: test the result, port your
 runtime calls deliberately, and keep v2 in place until the new application is
 ready.
 
-We are also evaluating an experimental migration assistant. It is not part of
-this beta release, and we will only recommend it once it has been validated
-against representative real-world v2 projects.
+The beta CLI also includes an experimental migration assistant:
+`wails3 migrate -d /path/to/v2-project -o /path/to/v3-project`. It creates a
+separate V3 project and a `MIGRATION.md` checklist, but it does not promise a
+zero-touch conversion. Review the generated project, port the listed V2 API
+calls, and report reproducible problems in the issue tracker.
 
 ## A candid note on the journey
 

diff --git a/docs/src/content/docs/guides/cli.mdx b/docs/src/content/docs/guides/cli.mdx
@@ -53,6 +53,28 @@ When provided, this flag will:
 3. Update the module name in `go.mod` to match the repository URL
 4. Add all files
 
+### `migrate`
+
+Migrates a Wails v2 project into a new Wails v3 project. This command is
+experimental and always requires review of the generated project.
+
+```bash
+wails3 migrate -d /path/to/v2-project -o /path/to/v3-project
+```
+
+The source project is left unchanged. The command maps deterministic project
+metadata, build assets, frontend setup, and configuration, then writes a
+`MIGRATION.md` report to the output directory. It does not rewrite application
+logic or remaining V2 runtime calls. Port the calls listed in the report,
+then run `go mod tidy`, `wails3 doctor`, `wails3 generate bindings`, and
+`wails3 dev`.
+
+Use `wails3 migrate --help` for all flags. Report reproducible migration
+failures in the [issue tracker](https://github.com/wailsapp/wails/issues) with
+the command, CLI version, operating system, `wails3 doctor` output, and the
+generated `MIGRATION.md`. Proposals to change migration behavior belong in a
+[Wails Enhancement Proposal](https://github.com/wailsapp/wails/tree/master/v3/wep).
+
 ### `dev`
 Runs the application in development mode. This will give you a live view of your frontend code, and you can make changes and see them reflected
 in the running application without having to rebuild the entire application. Changes to your Go code will also be detected and the application

diff --git a/docs/src/content/docs/migration/v2-to-v3.mdx b/docs/src/content/docs/migration/v2-to-v3.mdx
@@ -18,6 +18,40 @@ Wails v3 is a **complete rewrite** with significant improvements in architecture
 
 **Migration time:** 1-4 hours for typical applications
 
+## Automated Migration
+
+:::caution[Experimental]
+The `wails3 migrate` command is included in the V3 CLI, but it is experimental.
+It handles common project shapes well, but your mileage may vary: review the
+generated code and test your application thoroughly. If it stumbles on your
+project, please [open an issue](https://github.com/wailsapp/wails/issues) with
+the details so we can improve it. Pull requests are very welcome.
+:::
+
+The CLI can perform most of this guide for you:
+
+```bash
+wails3 migrate -d ./myv2project -o ./myv3project
+```
+
+The command migrates what maps deterministically and documents the rest. It does not rewrite your application logic and it does not generate compatibility layers: code that still uses the v2 API is left untouched, and every such location is listed in a generated `MIGRATION.md` with its concrete v3 replacement, so the remaining work is a clear checklist rather than a half-migrated codebase.
+
+What it migrates for you:
+
+- `main.go` is rewritten around `application.New()` + `app.Window.NewWithOptions()`, keeping your own code and comments intact. Options are mapped to their v3 equivalents, including platform-specific window options.
+- Structs listed in `Bind` become v3 services, and the `OnStartup`/`OnDomReady`/`OnShutdown`/`OnBeforeClose` callbacks are wired to their v3 counterparts (application events, `OnShutdown`, `ShouldQuit`).
+- `wails.json` is replaced by the v3 project files: a Taskfile-based build system and `build/config.yml` populated from your v2 metadata (product info, file associations, protocols).
+- `go.mod` swaps `wails/v2` for `wails/v3`; everything else is preserved.
+- The frontend is copied over and `@wailsio/runtime` is added to its dependencies. The generated `wailsjs/` directory is not carried over - it is v2 build output that cannot work with v3.
+
+What it documents for you (in `MIGRATION.md`):
+
+- Every call into the v2 `runtime` package, listed by file and line with the v3 replacement (for example `runtime.EventsEmit(ctx, ...)` becomes `app.Event.Emit(...)`). The project intentionally does not compile until these are ported - the compiler points at exactly the listed locations.
+- Every frontend import of `wailsjs/runtime` or `wailsjs/go/...`, with the `@wailsio/runtime` equivalent and the `wails3 generate bindings` workflow for bindings.
+- Options that need a human decision (menus, custom loggers, `EnumBind`, ...), each with instructions.
+
+The rest of this guide explains the underlying changes in depth - use it together with the generated checklist.
+
 ## Breaking Changes
 
 ### Application Initialisation
@@ -480,21 +514,24 @@ Events.Emit("action", data)
 }
 ```
 
-**v3 (wails.json):**
+**v3 (`build/config.yml`):**
 
-```json
-{
-  "name": "myapp",
-  "frontend": {
-    "dir": "./frontend",
-    "install": "npm install",
-    "build": "npm run build",
-    "dev": "npm run dev",
-    "devServerUrl": "http://localhost:5173"
-  }
-}
+```yaml
+version: '3'
+
+info:
+  productName: "myapp"
+  productIdentifier: "com.example.myapp"
+
+dev_mode:
+  root_path: .
 ```
 
+V3 project-level development and build commands are defined in the root
+`Taskfile.yml`. The generated project keeps frontend commands there and uses
+`build/config.yml` for application and packaging configuration. Do not create
+a V3 `wails.json` by copying the V2 file.
+
 ## Feature Mapping
 
 ### dialogs
@@ -673,6 +710,28 @@ wails3 generate bindings
 
 ## Getting Help
 
+### Reporting migration problems
+
+Migration tool failures are bugs. Before opening an issue, reduce the problem
+to the smallest reproducible V2 project you can and include:
+
+- the Wails V2 version and the V3 CLI version or commit;
+- the operating system and architecture;
+- the exact `wails3 migrate` command;
+- the command output and generated `MIGRATION.md`;
+- `wails3 doctor` output; and
+- a redacted project or minimal reproduction, if the project contains private
+  code.
+
+Open the report in the [Wails issue tracker](https://github.com/wailsapp/wails/issues)
+using the bug report template. Do not attach secrets, signing credentials, or
+private source code.
+
+If you want to propose a change to the migration behavior or V3 API, submit a
+[Wails Enhancement Proposal](https://github.com/wailsapp/wails/tree/master/wep)
+as a pull request. Product proposals should not be filed as ordinary feature
+requests.
+
 ### Resources
 
 - [Documentation](/quick-start/why-wails)

diff --git a/docs/src/content/docs/reference/cli.mdx b/docs/src/content/docs/reference/cli.mdx
@@ -21,6 +21,7 @@ wails3 <command> --help
 | Command | Description |
 |---------|-------------|
 | `wails3 init` | Create a new project from a template. Flags: `-n` (project name), `-t` (template, default `vanilla`), `-p` (Go package name, default `main`), `-d` (project directory, default `.`), `-q` (quiet), `-l` (list templates), `-mod` (Go module path), `--git` (Git repository URL), `--skipgomodtidy`, `-s` (skip remote-template warning), `--productname`/`--productdescription`/`--productversion`/`--productcompany`/`--productcopyright`/`--productcomments`/`--productidentifier`. |
+| `wails3 migrate` | Migrate a V2 project into a separate V3 output directory. Experimental: use `-d` for the V2 project, `-o` for the new output directory, `-f` to allow a non-empty output directory, `-q` for quiet output, and `-skipgomodtidy` to skip dependency cleanup. Review the generated `MIGRATION.md`; application logic and remaining V2 API calls require manual porting. |
 | `wails3 dev` | Run the application in development mode with frontend hot reload. Flags: `--config` (default `./build/config.yml`), `--port` (Vite dev port), `-s` (enable HTTPS). |
 | `wails3 build` | Build the project. Thin wrapper around the Taskfile `build` task. Flags: `--tags` (forwarded as `EXTRA_TAGS=`), `--obfuscated` (build with Garble; see [Obfuscated Builds](/guides/build/obfuscation)), `--garbleargs` (extra flags forwarded to `garble` before the `build` subcommand). |
 | `wails3 package` | Run the platform-specific `package` Taskfile task. |

diff --git a/v3/cmd/wails3/main.go b/v3/cmd/wails3/main.go
@@ -44,6 +44,8 @@ func main() {
 
 	app.NewSubCommandFunction("dev", "Run in Dev mode", commands.Dev)
 
+	app.NewSubCommandFunction("migrate", "Migrate a Wails v2 project to v3 (experimental)", commands.Migrate)
+
 	pkg := app.NewSubCommand("package", "Package application")
 	var pkgFlags flags.Package
 	pkg.AddFlags(&pkgFlags)