feat(v3): wails3 migrate - automated v2 to v3 project migration

[taliesin-ai]

Summary

Warning

This command is experimental. It handles the common v2 project shapes well, but your mileage may vary: generated projects should be reviewed and tested thoroughly. Please report anything it gets wrong via the issue tracker; PRs improving the tool are very welcome. The CLI, the generated MIGRATION.md and the docs all carry this notice.

wails3 migrate -d ./myv2project -o ./myv3project helps convert a Wails v2 project into a Wails v3 project.

The design principle: migrate what maps deterministically, document the rest, and never leave code half-rewritten. The tool does not modify application logic and does not generate compatibility layers - code that still uses the v2 API is copied untouched, every such location is enumerated in a generated MIGRATION.md with its concrete v3 replacement, and the compiler points at exactly those locations until they are ported.

What it migrates

Parse (syntax-only go/parser, works without the v2 module in the module cache): wails.json (with v2's defaulting rules), go.mod, the options.App literal inside wails.Run(...), the Bind entries, lifecycle callbacks and embed directives.

Generate:

• main.go rewritten around application.New() + app.Window.NewWithOptions() via textual surgery: only the wails.Run statement and the import block are replaced, all other user code and comments are preserved byte-for-byte, then gofmt'd. The error-handling shape is preserved.
• Data-driven option mapping (geometry, start state, background colour, frameless, asset server/handler/middleware, single instance, drag-and-drop, Windows/Mac/Linux platform options incl. enum/preset translation such as mac.TitleBarHiddenInset() -> application.MacTitleBarHiddenInset). Title maps to both Options.Name and the window title.
• Bind -> Services. Lifecycle hooks are wired natively in the generated main file: OnStartup -> events.Common.ApplicationStarted, OnDomReady -> events.Common.WindowRuntimeReady, OnShutdown -> Options.OnShutdown, OnBeforeClose -> a ShouldQuit wrapper. Public v3 API only, no shims.
• v3 build system scaffolded through the existing init/build-assets machinery: root Taskfile (package manager carried over from frontend:install), build/ assets and build/config.yml populated from the v2 metadata. File associations and protocols move from wails.json into config.yml (with an UpdateBuildAssets pass so plists/manifests pick them up). The bundle id keeps v2's com.wails.<name> convention so migrated apps keep their identity. The v2 build/appicon.png is preserved.
• go.mod: wails/v2 -> wails/v3 (at version.LatestStable()), go directive raised to 1.24, all other requires kept.
• Frontend copied over with @wailsio/runtime added to package.json. The generated wailsjs/ directory is not carried over - it is v2 build output that cannot work against a v3 backend.

What it documents instead of migrating

MIGRATION.md contains a Port these to the v3 API table:

• every call into the v2 runtime package, by file:line, with the concrete v3 replacement (e.g. runtime.EventsEmit -> app.Event.Emit(name, data...); runtime.WindowSetTitle -> window.SetTitle(title) via app.Window.Current(); dialogs -> the v3 builder API; MessageDialog -> button callbacks). ~60 v2 functions are mapped.
• every frontend import of wailsjs/runtime or wailsjs/go/..., with the @wailsio/runtime equivalent and the wails3 generate bindings workflow.
• plus Manual steps for options needing a human (menus, custom loggers, EnumBind, custom Windows themes, ...) and notes on everything else the tool did.

Deliberate consequences:

• A project with remaining v2 call sites does not compile until they are ported - that is the honest state, and the report lists exactly where to go.
• go mod tidy is skipped (with a warning) while v2 call sites remain: tidying would re-add the v2 dependency and let the old calls compile, only to fail at runtime inside a v3 application. MIGRATION.md spells this out; after porting, the user runs tidy + wails3 generate bindings.

Verified

• Unit tests for the parser, option mapper, main-file generator, go.mod transform, the call-site advisor (Go + frontend) and the frontend copy rules (internal/migrate), plus end-to-end command tests (internal/commands) covering the full run, the MIGRATION.md checklist contents, untouched-source guarantees, output-safety guards and non-v2 rejection.
• Manually migrated a v2 template-derived fixture with lifecycle hooks, runtime calls and file associations: the checklist lists each call site correctly and the project refuses to build until they are ported (as designed).
• A fixture without v2 runtime usage compiles and runs: the natively wired OnStartup (ApplicationStarted event) fired, confirmed via a marker file.
• Options mapping verified end to end earlier in development, including a live webview round-trip of events and bindings against the published @wailsio/runtime@3.0.0-alpha.95.
• gofmt/go vet clean; full internal/commands and internal/migrate suites pass.

Docs

The Migrating from v2 to v3 guide now leads with the automated path, describing exactly what is migrated and what is documented, under an Experimental caution.

Notes for review

• Earlier iterations of this branch shipped a v2-runtime compatibility bridge (first as pkg/v2compat, then generated into the project) and generated wailsjs JS shims. Both were removed by design decision: compatibility layers invite code to stay on (or newly adopt) the v2 API, and half-automatic rewriting risks silently changing behaviour. The advise-first model keeps the tool honest. The history is in the branch commits if we ever want to revisit.
• templates.Install mutates ProjectDir, chdirs and prints via bare fmt.Print; the migrate command works around all three (restores cwd, silences stdout for the scratch scaffold). Happy to refactor Install instead if preferred.
• When run from a dev build, the generated go.mod uses version.LatestStable() (version.txt) rather than v3.0.0-dev, so the require always resolves.

[coderabbitai]

Important

Review skipped

Draft detected.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 95467bcf-4137-4d94-960c-b487b25fae79

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/wails3-migrate-command

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}