* fix(v3): fixed update plist, close https://github.com/wailsapp/wails/issues/4636
* chore: update changelog
* feat: add recursive merge support for nested plist dictionaries
Previously, the plist merge was shallow - nested dictionaries were
completely replaced rather than recursively merged. This caused custom
nested configurations to be lost during build asset updates.
Now nested dictionaries are recursively merged, preserving custom keys
at all levels while still allowing new keys to be added and existing
keys to be updated.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
* refactor: replace temp directory with backup-based plist merge
Instead of extracting to a temp directory and copying files over,
we now:
1. Rename existing plists to .plist.bak
2. Extract new assets directly to target
3. Merge backup content into newly extracted plists
4. Clean up backup files
This is simpler, more crash-safe (backups remain if process crashes),
and avoids the overhead of a temp directory and file copying.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
---------
Co-authored-by: Lea Anthony <lea.anthony@gmail.com>
Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>
* Add window name header when making webview requests
* Add changelog item
* Update PR no in changelog entry
---------
Co-authored-by: Lea Anthony <lea.anthony@gmail.com>
Replace <Aside type="caution"> JSX with :::caution markdown syntax
to fix the docs build error.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
* Update `RawMessageHandler` to include `originInfo` parameter in documentation
- Expanded examples and handler signature to reflect the additional `originInfo` parameter.
- Detailed `OriginInfo` structure and its platform-specific behaviors added.
* Expand `raw-messages` documentation to include origin validation guidance
* Add support for origin tracking in raw message handling
- Implemented origin and top origin tracking for web messages from JavaScript.
- Updated `RawMessageHandler` to include `originInfo`.
- Added cross-platform support for retrieving the origin of messages in macOS, Windows, and Linux.
* fix build
* fix build
* fix build
* fix build
* fix build
* Fix nil checks and string handling for message origins across platforms
- Ensure proper fallback to empty strings for `origin` and `topOrigin` when errors or nil values are encountered.
- Normalize handling of `message.body` to account for non-NSString values in macOS.
* add docs
* Remove unused doc
* update changelog
* fix build
---------
Co-authored-by: Lea Anthony <lea.anthony@gmail.com>
* Rename `HandleCustomProtocol` to `HandleOpenURL` and add universal link support on macOS.
* Update changelog.
* add docs
* add docs
---------
Co-authored-by: Lea Anthony <lea.anthony@gmail.com>
- Add RawMessageHandler section to Application API reference
- Add System.invoke() to Frontend Runtime reference
- Create comprehensive Raw Messages guide
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Update tests to match the new wrapTask behavior introduced in the
cross-platform build system:
- Task names are now prefixed with platform (e.g., linux:build)
- ARCH argument is automatically added based on GOARCH
- GOOS/GOARCH args are filtered from remaining args
- Environment variables are respected with arg overrides
Also adds test for the new SignWrapper command.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Use NullLogger instead of DefaultPtermLogger during tests to prevent
console output. Warnings are still written to warnings.log for
comparison. This prevents GitHub Actions Go problem matcher from
treating any warning-like output as errors.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Update test to prefix warnings with [warn] when writing to warnings.log,
and update all fixture files accordingly. This prevents the Go problem
matcher from treating diff output as errors during CI.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Add [warn] prefix to generator warnings to prevent the Go problem
matcher from interpreting them as errors. The matcher regex matches
file.go:line:col: patterns, causing CI failures on valid warning output.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Remove the paths filter that was causing v3 build and test jobs to be
skipped when PRs targeting v3-alpha didn't contain changes in the v3/
directory. This ensures all PRs to v3-alpha are properly tested.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- Add global defaults config stored in ~/.config/wails/defaults.yaml
- Add light/dark mode toggle with theme persistence
- Add PKGBUILD support to Linux build formats display
- Add macOS signing clarification (public identifiers vs Keychain storage)
- Fix spinner animation using CSS animate-spin
- Add signing defaults for macOS and Windows code signing
- Compact defaults page layout with 2-column design
- Add Wails logo with proper light/dark theme variants
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- Add retry button to dependencies page when missing deps exist
- Add loading spinner animation when checking dependencies
- Merge required/optional dependency lists with (optional) indicator
- Show single combined install command for all missing system packages
- Remove individual install commands and redundant status messages
- Fix duplicate npm appearing in both required and optional sections
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- Add Apple, Windows, and Tux (Linux) SVG logos in welcome screen
- Remove extra "v" prefix from Wails version display
- Remove "go" prefix from Go version display
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- Redesign as classic Windows-style page-by-page wizard
- Add install commands from doctor/packagemanager for missing deps
- Show copyable commands for system package installs (pacman, apt, etc)
- Add external links for npm (nodejs.org) and Docker (docker.com)
- Add API endpoint to run install commands from wizard
- Show breadcrumb navigation: Welcome > Dependencies > Docker > Complete
- Add Cancel button and Back/Next navigation
- Dependencies page shows Required/Optional sections with status
- Docker page shows cross-compilation setup with image build option
- Complete page has copyable next steps commands
- Include InstallCommand and HelpURL fields in DependencyStatus
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- Add setup.go command that launches the web-based setup wizard
- Register `wails3 setup` command in main.go
- Fix SignWrapper registration to use NewSubCommand pattern
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- Replace incorrect OnStartup hook with actual v3 lifecycle mechanisms
- Document Services with ServiceStartup/ServiceShutdown interfaces
- Document application-level hooks: ShouldQuit, OnShutdown, PostShutdown
- Document event-based lifecycle with OnApplicationEvent and OnWindowEvent
- Document window hooks with RegisterHook for cancellable events
- Add correct platform-specific defaults for quit-on-last-window-close
- Add JavaScript example to services Quick Start
- Make Taskfile dev task depend on setup task
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
- Add path filters to only trigger on docs/** changes
- Remove incorrectly placed GH_TOKEN env variable
- This should make the workflow trigger properly
- Install D2 binary in GitHub Actions before building docs
- Remove DEVELOPER_GUIDE.md temporary file from docs content
- This fixes the docs build failure on GitHub Pages
This commit represents a complete redesign of the Wails v3 documentation structure
and includes all recent v3-alpha updates.
## Major Changes
### Documentation Restructure
- Migrated from /learn to organized /features, /guides, /reference structure
- Created new Quick Start section with installation and first app guides
- Added comprehensive Concepts section explaining architecture and lifecycle
- Reorganized Contributing section with detailed guides for different contribution types
- Added complete API Reference with separate pages for each major component
### New Documentation
- Custom URL Protocols guide with NSIS automatic registration
- Windows Packaging guide with NSIS, MSI, and MSIX options
- Typed Events system with TypeScript binding generation
- Complete menu documentation (Application, Context, System Tray)
- Comprehensive dialog documentation (File, Message, Custom)
- Window management guides (Basics, Events, Frameless, Multiple Windows)
- Bindings documentation (Services, Methods, Models, Best Practices)
- New tutorials: Todo app and Notes app (vanilla JS)
### v3-alpha API Updates
- Typed Events: RegisterEvent[T] with strict mode and binding generation
- Custom Protocols: NSIS macros for automatic Windows protocol registration
- System Tray: Windows Show/Hide now fully functional with tooltip limits
- Window Hidden: Fixed white flash on Windows when creating hidden windows
- Notifications: Corrected import path to pkg/services/notifications
- Frontend Runtime: Events.Emit now returns Promise<boolean> for cancellation
### Documentation Improvements
- Updated all code examples to use @wailsio/runtime imports
- Added platform-specific event tables and examples
- Created comprehensive event reference with use cases
- Added security best practices and validation patterns
- Improved code examples with real-world use cases
- Added troubleshooting sections and common patterns
### Files
- Created: 60+ new documentation pages
- Deleted: Old /learn structure (13 files)
- Modified: 15 existing files for v3-alpha compatibility
- Added: Tutorial assets and showcase images
* Fix Windows systray icon regression (#4704)
This fixes a regression introduced in commit d58d4ba where the systray
icon no longer defaults to the application icon when no custom icon is
provided.
The issue was that the default icon loading was changed from:
defaultIcon := w32.LoadIconWithResourceID(w32.GetModuleHandle(""), w32.RT_ICON)
To:
defaultIcon := getNativeApplication().windowClass.Icon
This caused the systray to display the default Wails icon instead of
the application's custom icon.
The fix reverts the default icon loading back to using
w32.LoadIconWithResourceID with w32.RT_ICON, which correctly loads
the application's icon resource.
Fixes: #4704
* Update changelog for systray icon fix
---------
Co-authored-by: Claude <noreply@anthropic.com>
* Add strong event typings
* Make `EmitEvent` take one data argument only
* Add event registration logic
* Report event cancellation to the emitter
* Prevent registration of system events
* Add support for typed event data initialisation
* Binding generation for events
* Tests for event bindings
* Add vite plugin for typed events
* Fix dev command execution order
Co-authored-by: Fabio Massaioli <fabio.massaioli@gmail.com>
* Propagate module path to templates
* Update templates
Co-authored-by: Ian VanSchooten <ian.vanschooten@gmail.com>
* Go mod tidy for examples
* Switch to tsconfig.json for jetbrains IDE support
* Replace jsconfig in example
* Convert vite plugin to typescript
* Downgrade vite for now
The templates all use 5.x
* Remove root plugins dir from npm files
It's now '/dist/plugins'
* Include types for Create
But keep out of the docs
* Assign a type for cancelAll results
* Restore variadic argument in EmitEvent methods
* Support registered events with void data
* Test cases for void alias support
* Support strict mode
* Support custom event hooks
* Update docs
* Update changelog
* Testdata for typed events
* Test data for void alias support
* fix webview_window emit event
* Update changelog.mdx
* Update events
* Fix generator test path normalization for cross-platform compatibility
The generator tests were failing on CI because they compared absolute file paths
in warning messages. These paths differ between development machines and CI environments.
Changes:
- Normalize file paths in warnings to be relative to testcases/ directory
- Handle both Unix and Windows path separators
- Use Unix line endings consistently in test output
- Update all test expectation files to use normalized paths
This ensures tests pass consistently across different environments including
Windows, macOS, Linux, and CI systems.
* Remove stale comment
* Handle errors returned from validation
* Restore variadic argument to Emit (fix bad rebase)
* Event emitters return a boolean
* Don't use `EmitEvent` in docs
Supposedly it's for internal use, according to comment
* Fix event docs (from rebase)
* Ensure all templates specify @wailsio/runtime: "latest"
* Fix Windows test failure due to CRLF line endings
The test was failing on Windows because:
1. Hardcoded "\n" was being used instead of render.Newline when writing
warning logs, causing CRLF vs LF mismatch
2. The render package import was missing
3. .got.log files weren't being skipped when building expected file list
Changes:
- Add render package import
- Use render.Newline instead of hardcoded "\n" for cross-platform compatibility
- Skip .got.log files in test file walker
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
* Fix template tests by using local runtime package
The template tests were failing because they were installing @wailsio/runtime@latest from npm, which doesn't have the new vite plugin yet. This change packs the local runtime and uses it in template tests instead.
Changes:
- Pack the runtime to a tarball in test_js job
- Upload the runtime package as an artifact
- Download and install the local runtime in template tests before building
- Update cleanup job to delete the runtime package artifact
* Apply suggestion from @leaanthony
* Fix: Install local runtime in frontend directory with correct path
The previous fix wasn't working because:
1. npm install was run in the project root, not in frontend/
2. wails3 build runs npm install again, which would reinstall from npm
Fixed by:
- Using npm pkg set to modify package.json to use file:// protocol
- This ensures subsequent npm install calls use the local tarball
* Fix Vue template syntax conflicts with Go template delimiters
The Vue templates were converted to .tmpl files to support dynamic module
paths, but Vue's template syntax {{ }} conflicts with Go's template syntax.
Fixed by escaping Vue template braces:
- {{ becomes {{"{{"}}
- }} becomes {{"}}"}}
This allows the Go template engine to output the literal {{ }} for Vue to process.
* Fix Vue template escaping and Windows shell compatibility
Two issues fixed:
1. Vue template escaping: Changed from {{"{{"}} to {{ "{{" }}
- The previous syntax caused "missing value for command" error
- Correct Go template syntax uses spaces between delimiters and strings
2. Windows PowerShell compatibility: Added 'shell: bash' to template generation step
- The bash syntax (ls, head, $()) doesn't work in PowerShell
- Git Bash is available on all GitHub runners including Windows
* Fix: test_templates depends on test_js for runtime package artifact
The runtime-package artifact is created in test_js job, not test_go.
Added test_js to the needs array so the artifact is available for download.
* Fix Windows path compatibility for runtime package artifact
Changed from absolute Unix path '/tmp/wails-runtime' to relative path
'wails-runtime-temp' which works cross-platform. Using realpath to
convert to absolute path for file:// URL in npm pkg set command.
* Fix realpath issue on Windows for runtime package
realpath on Windows Git Bash was producing malformed paths with duplicate
drive letters (D:\d\a\...). Replaced with portable solution using pwd
that works correctly across all platforms.
* Use pwd -W on Windows to get native Windows paths
Git Bash's pwd returns Unix-style paths (/d/a/wails/wails) which npm
then incorrectly resolves as D:/d/a/wails/wails. Using pwd -W returns
native Windows paths (D:\a\wails\wails) that npm can handle correctly.
This is the root cause of all the Windows path issues.
* Improve typechecking for Events.Emit()
* [docs] Clarify where `Events` is imported from in each example
* Add docs for runtime Events.Emit()
* Revert to v2-style Events.Emit (name, data)
* Update changelog
---------
Co-authored-by: Fabio Massaioli <fabio.massaioli@gmail.com>
Co-authored-by: Atterpac <Capretta.Michael@gmail.com>
Co-authored-by: Lea Anthony <lea.anthony@gmail.com>
Co-authored-by: Claude <noreply@anthropic.com>
* convert file to use lf line-endings
* fileexplorer fix opening dir on Linux
* include update in unreleased changelog
---------
Co-authored-by: Angus Dippenaar <angusdippenaar@gmail.com>
* Fix Windows build error with go-webview2 v1.0.22
Fixes#4513
The go-webview2 library changed the MessageCallback signature in v1.0.22
from `func(string)` to `func(message string, sender *ICoreWebView2, args *ICoreWebView2WebMessageReceivedEventArgs)`.
This caused a build error for users:
```
cannot use w.processMessage (value of type func(message string)) as
func(message string, sender *ICoreWebView2, args *ICoreWebView2WebMessageReceivedEventArgs)
value in assignment
```
Changes:
- Updated processMessage signature to match go-webview2 v1.0.22
- Upgraded go-webview2 dependency from v1.0.21 to v1.0.22
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
* Fix Windows build error with go-webview2 v1.0.22
Fixes#4513
The go-webview2 library changed the MessageCallback signature in v1.0.22
from `func(string)` to `func(message string, sender *ICoreWebView2, args *ICoreWebView2WebMessageReceivedEventArgs)`.
This caused a build error for users:
```
cannot use w.processMessage (value of type func(message string)) as
func(message string, sender *ICoreWebView2, args *ICoreWebView2WebMessageReceivedEventArgs)
value in assignment
```
Changes:
- Updated processMessage signature to match go-webview2 v1.0.22
- Upgraded go-webview2 dependency from v1.0.21 to v1.0.22
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
---------
Co-authored-by: Claude <noreply@anthropic.com>
