Skip to content

[v3] update docs to reflect changes from Manager API Refactoring#4476

Merged
leaanthony merged 6 commits into
wailsapp:v3-alphafrom
yulesxoxo:update-docs-2025-08-05
Aug 5, 2025
Merged

[v3] update docs to reflect changes from Manager API Refactoring#4476
leaanthony merged 6 commits into
wailsapp:v3-alphafrom
yulesxoxo:update-docs-2025-08-05

Conversation

@yulesxoxo

@yulesxoxo yulesxoxo commented Aug 4, 2025

Copy link
Copy Markdown
Contributor

Description

  • Update docs and examples to match the changes from feat: Complete App API restructuring with organized manager pattern #4359

  • Change minimum required Go version to 1.24 in the Getting Started -> Installation

  • Updated some examples to use app := application.Get()
    Example before:

    func (a *App) UpdateData() {
        a.app.EmitEvent("my-app:data-updated", map[string]interface{}{
            "timestamp": time.Now(),
            "count": 42,
        })
    }

    I believe the a.app example here would just be confusing to new people especially because App is not defined in the scope so it becomes ambiguous as to what it is.

    After:

    func (s *Service) UpdateData() {
        app := application.Get()
        app.Event.EmitEvent(&application.CustomEvent{
            Name: "my-app:data-updated",
            Data: map[string]interface{}{
                "timestamp": time.Now(),
                "count": 42,
            },         
        })
    }

Just a quick idea I'd like to sneak in:
It would make sense to add some linter or similar for the md/mdx files usage of tabs/spaces is very inconsistent.

Checklist:

  • I have updated website/src/pages/changelog.mdx with details of this PR
  • My code follows the general coding style of this project
  • I have performed a self-review of my own code
  • I have commented my code, particularly in hard-to-understand areas
  • I have made corresponding changes to the documentation
  • My changes generate no new warnings
  • I have added tests that prove my fix is effective or that my feature works
  • New and existing unit tests pass locally with my changes

Summary by CodeRabbit

  • Documentation
    • Updated all code examples to use the latest API patterns for creating windows, menus, system trays, and handling events, replacing direct method calls on the app instance with structured field access (e.g., app.Window.New(), app.Menu.New()).
    • Increased the minimum required Go version in installation instructions to 1.24.
    • Improved clarity and completeness of example code snippets, including expanded and better-formatted examples.
    • Updated receiver types and event emission patterns in backend service examples to reflect new conventions.

@coderabbitai

coderabbitai Bot commented Aug 4, 2025

Copy link
Copy Markdown
Contributor

Walkthrough

This update refactors documentation examples to reflect a new API structure in the application framework. It replaces direct method calls on the app object for window, menu, system tray, and event management with calls through respective manager fields (e.g., app.Window.New(), app.Menu.New(), app.Event.On()). Some receiver types in backend examples are also updated.

Changes

Cohort / File(s) Change Summary
Window Creation API Update
docs/src/content/docs/contributing/codebase-layout.mdx, docs/src/content/docs/contributing/runtime-internals.mdx, docs/src/content/docs/guides/customising-windows.mdx, docs/src/content/docs/guides/gin-routing.mdx, docs/src/content/docs/learn/application-menu.mdx, docs/src/content/docs/learn/clipboard.mdx, docs/src/content/docs/learn/context-menu.mdx, docs/src/content/docs/tutorials/01-creating-a-service.mdx
Changed window creation from app.NewWebviewWindow* to app.Window.New* in documentation examples.
Event API Refactor
docs/src/content/docs/guides/custom-protocol-association.mdx, docs/src/content/docs/guides/events-reference.mdx, docs/src/content/docs/guides/file-associations.mdx, docs/src/content/docs/guides/gin-services.mdx, docs/src/content/docs/learn/environment.mdx, docs/src/content/docs/learn/events.mdx, docs/src/content/docs/learn/screens.mdx
Updated event registration and emission from direct app.On*/app.EmitEvent to app.Event.On*/app.Event.Emit*. Backend receiver types updated in some examples.
Menu and System Tray API Update
docs/src/content/docs/guides/menus.mdx, docs/src/content/docs/learn/systray.mdx, docs/src/content/docs/whats-new.md
Changed menu and system tray creation from app.Menus.New()/app.NewMenu()/app.NewSystemTray() to app.Menu.New()/app.SystemTray.New().
Environment and Miscellaneous Property Access
docs/src/content/docs/learn/browser.mdx
Changed property access from app.Environment.Info().Debug to app.Env.Info().Debug.
Go Version Requirement Update
docs/src/content/docs/getting-started/installation.mdx
Updated minimum Go version requirement from 1.23 to 1.24.

Sequence Diagram(s)

sequenceDiagram
    participant Developer
    participant App
    participant WindowManager
    participant EventManager
    participant MenuManager

    Developer->>App: app.Window.New(options)
    App->>WindowManager: New(options)
    WindowManager-->>Developer: Window instance

    Developer->>App: app.Event.On(event, handler)
    App->>EventManager: On(event, handler)
    EventManager-->>Developer: Subscription

    Developer->>App: app.Menu.New()
    App->>MenuManager: New()
    MenuManager-->>Developer: Menu instance
Loading

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~8 minutes

Possibly related PRs

Suggested labels

cli

Suggested reviewers

  • leaanthony

Poem

Hopping through docs with a whisk of my tail,
I nibbled old APIs, left new ones in my trail.
Windows and menus, events all anew—
Now app.Window.New() is what you’ll do!
With every example, the docs grow bright,
A carrot for clarity, and code done right. 🥕

Note

⚡️ Unit Test Generation is now available in beta!

Learn more here, or try it out under "Finishing Touches" below.


📜 Recent review details

Configuration used: .coderabbit.yaml
Review profile: CHILL
Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 71fcf9e and 91cefdc.

📒 Files selected for processing (4)
  • docs/src/content/docs/guides/events-reference.mdx (2 hunks)
  • docs/src/content/docs/guides/gin-services.mdx (4 hunks)
  • docs/src/content/docs/learn/events.mdx (5 hunks)
  • v3/UNRELEASED_CHANGELOG.md (1 hunks)
✅ Files skipped from review due to trivial changes (1)
  • v3/UNRELEASED_CHANGELOG.md
🚧 Files skipped from review as they are similar to previous changes (3)
  • docs/src/content/docs/guides/gin-services.mdx
  • docs/src/content/docs/learn/events.mdx
  • docs/src/content/docs/guides/events-reference.mdx
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (4)
  • GitHub Check: semgrep-cloud-platform/scan
  • GitHub Check: Run Go Tests v3 (macos-latest, 1.24)
  • GitHub Check: Run Go Tests v3 (ubuntu-latest, 1.24)
  • GitHub Check: Run Go Tests v3 (windows-latest, 1.24)
✨ Finishing Touches
🧪 Generate unit tests
  • Create PR with unit tests
  • Post copyable unit tests in a comment

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
🪧 Tips

Chat

There are 3 ways to chat with CodeRabbit:

  • Review comments: Directly reply to a review comment made by CodeRabbit. Example:
    • I pushed a fix in commit <commit_id>, please review it.
    • Explain this complex logic.
    • Open a follow-up GitHub issue for this discussion.
  • Files and specific lines of code (under the "Files changed" tab): Tag @coderabbitai in a new review comment at the desired location with your query. Examples:
    • @coderabbitai explain this code block.
  • PR comments: Tag @coderabbitai in a new PR comment to ask questions about the PR branch. For the best results, please provide a very specific query, as very limited context is provided in this mode. Examples:
    • @coderabbitai gather interesting stats about this repository and render them as a table. Additionally, render a pie chart showing the language distribution in the codebase.
    • @coderabbitai read src/utils.ts and explain its main purpose.
    • @coderabbitai read the files in the src/scheduler package and generate a class diagram using mermaid and a README in the markdown format.

Support

Need help? Create a ticket on our support page for assistance with any issues or questions.

CodeRabbit Commands (Invoked using PR comments)

  • @coderabbitai pause to pause the reviews on a PR.
  • @coderabbitai resume to resume the paused reviews.
  • @coderabbitai review to trigger an incremental review. This is useful when automatic reviews are disabled for the repository.
  • @coderabbitai full review to do a full review from scratch and review all the files again.
  • @coderabbitai summary to regenerate the summary of the PR.
  • @coderabbitai generate docstrings to generate docstrings for this PR.
  • @coderabbitai generate sequence diagram to generate a sequence diagram of the changes in this PR.
  • @coderabbitai generate unit tests to generate unit tests for this PR.
  • @coderabbitai resolve resolve all the CodeRabbit review comments.
  • @coderabbitai configuration to show the current CodeRabbit configuration for the repository.
  • @coderabbitai help to get help.

Other keywords and placeholders

  • Add @coderabbitai ignore anywhere in the PR description to prevent this PR from being reviewed.
  • Add @coderabbitai summary to generate the high-level summary at a specific location in the PR description.
  • Add @coderabbitai anywhere in the PR title to generate the title automatically.

Documentation and Community

  • Visit our Documentation for detailed information on how to use CodeRabbit.
  • Join our Discord Community to get help, request features, and share feedback.
  • Follow us on X/Twitter for updates and announcements.

@dosubot dosubot Bot added the size:L This PR changes 100-499 lines, ignoring generated files. label Aug 4, 2025
@github-actions github-actions Bot added the Documentation Improvements or additions to documentation label Aug 4, 2025

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 3

🔭 Outside diff range comments (6)
docs/src/content/docs/contributing/runtime-internals.mdx (1)

42-45: Out-of-date API reference – NewWebviewWindow should be app.Window.New()
The explanatory text still refers to the old NewWebviewWindow constructor even though the surrounding example was migrated to app.Window.New(). This inconsistency will confuse readers who try to search for a non-existent symbol.

-`NewWebviewWindow` delegates to `internal/runtime/webview_window_*.go` where
+# `app.Window.New()` delegates to `internal/runtime/webview_window_*.go` where

Please update the method name (and any additional wording) to match the refactored Manager API.

docs/src/content/docs/guides/gin-routing.mdx (1)

275-288: Mismatch between frontend → backend event route paths

The backend registers the endpoint at "/events/emit" (Line 275) yet the JavaScript poly-fill forwards requests to "/api/events/emit" while intercepting "/wails/events/emit".
Unless additional reverse-proxying exists, one of these paths is wrong and events will 404.

- await fetch('/api/events/emit', {
+ await fetch('/events/emit', {
docs/src/content/docs/learn/systray.mdx (1)

115-121: Callback signature incorrect – will not compile

MenuItem.OnClick expects func(ctx *application.Context), but the example supplies a zero-arg lambda:

-menu.Add("Open").OnClick(func() {
-    window.Show()
-})
+menu.Add("Open").OnClick(func(ctx *application.Context) {
+    window.Show()
+})

The same applies to the “Quit” item.

docs/src/content/docs/guides/menus.mdx (1)

35-40: _ "embed" is invalid – example will not compile

Blank-ident importing embed is a compile-time error. The correct import is:

-import (
-   _ "embed"
+import (
+   "embed"

Without this fix, users copying the snippet will hit expected 'alias' or '.', found '_'.

docs/src/content/docs/whats-new.md (1)

109-114: Replace blank-identifier import for embed

The example uses //go:embed assets but imports embed with _, which does not work:

import (
    _ "embed" // ← compile error

Correct form:

-import (
-    _ "embed"
+import (
+    "embed"

This change is required for the snippet to compile.

docs/src/content/docs/learn/clipboard.mdx (1)

62-67: Remove unused time import – snippet will not compile

time is imported but never referenced after the switch to app.Window.New(), causing compile: imported and not used: "time".

-import (
-    "log"
-    "runtime"
-    "time"
-    "github.com/wailsapp/wails/v3/pkg/application"
-)
+import (
+    "log"
+    "runtime"
+    "github.com/wailsapp/wails/v3/pkg/application"
+)
♻️ Duplicate comments (1)
docs/src/content/docs/tutorials/01-creating-a-service.mdx (1)

418-422: Same pointer/value concern applies here

Replicate whichever fix you apply above to keep the second example compiling.

🧹 Nitpick comments (8)
docs/src/content/docs/guides/gin-routing.mdx (2)

94-101: Window centering option silently dropped

Centered: true was removed from the WebviewWindowOptions.
If the example is meant to open a centered window (as older docs did) add the explicit option or a comment explaining the new default.


550-553: Listener added but never removed

For long-running examples it’s often good practice to demonstrate removal of global listeners to avoid leaks:

cancel := app.Event.On("gin-button-clicked", func(e *application.CustomEvent){ ... })
defer cancel() // after app.Run()
docs/src/content/docs/guides/customising-windows.mdx (2)

53-57: Option struct imported but not aliased

Because the snippet dropped application. from enum names elsewhere, consider importing the package with an alias to shorten the call site, e.g.:

import app "github.com/wailsapp/wails/v3/pkg/application"

Purely stylistic—feel free to ignore.


113-117: Missing Windows build-tag guard

The w32 flags are Windows-only; placing this snippet inside a file guarded by //go:build windows avoids accidental compilation errors on other OSs.

docs/src/content/docs/learn/events.mdx (1)

460-466: Menu event examples compile, but note platform guard

events.Mac.* constants only exist on darwin builds; adding a comment or build-tag hint would help Windows/Linux readers.

docs/src/content/docs/guides/menus.mdx (1)

10-14: Update the wording to match the refactored API

The paragraph still references “the Menus manager”, but the code and API have moved to Menu.
Keeping terminology consistent avoids confusion for readers following the guide.

docs/src/content/docs/learn/application-menu.mdx (1)

249-253: Consider capturing the returned window handle

app.Window.New() returns a *application.WebviewWindow.
If you intend to configure the window later (size, URL, events, etc.) the example should store the returned value:

-    // Create main window
-    app.Window.New()
+    // Create main window
+    mainWindow := app.Window.New()
+    _ = mainWindow // configure later if required

This keeps the snippet flexible without changing its current behaviour.

docs/src/content/docs/learn/clipboard.mdx (1)

111-115: Optionally keep a reference to the new window

As in other docs, capturing the returned window pointer makes future configuration straightforward:

-    app.Window.New()
+    mainWindow := app.Window.New()
+    _ = mainWindow // use if additional setup is required
📜 Review details

Configuration used: .coderabbit.yaml
Review profile: CHILL
Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between d863e52 and 6b17ea9.

📒 Files selected for processing (20)
  • docs/src/content/docs/contributing/codebase-layout.mdx (1 hunks)
  • docs/src/content/docs/contributing/runtime-internals.mdx (1 hunks)
  • docs/src/content/docs/getting-started/installation.mdx (1 hunks)
  • docs/src/content/docs/guides/custom-protocol-association.mdx (1 hunks)
  • docs/src/content/docs/guides/customising-windows.mdx (2 hunks)
  • docs/src/content/docs/guides/events-reference.mdx (2 hunks)
  • docs/src/content/docs/guides/file-associations.mdx (1 hunks)
  • docs/src/content/docs/guides/gin-routing.mdx (4 hunks)
  • docs/src/content/docs/guides/gin-services.mdx (4 hunks)
  • docs/src/content/docs/guides/menus.mdx (8 hunks)
  • docs/src/content/docs/learn/application-menu.mdx (1 hunks)
  • docs/src/content/docs/learn/browser.mdx (1 hunks)
  • docs/src/content/docs/learn/clipboard.mdx (1 hunks)
  • docs/src/content/docs/learn/context-menu.mdx (1 hunks)
  • docs/src/content/docs/learn/environment.mdx (3 hunks)
  • docs/src/content/docs/learn/events.mdx (5 hunks)
  • docs/src/content/docs/learn/screens.mdx (2 hunks)
  • docs/src/content/docs/learn/systray.mdx (2 hunks)
  • docs/src/content/docs/tutorials/01-creating-a-service.mdx (2 hunks)
  • docs/src/content/docs/whats-new.md (5 hunks)
🧰 Additional context used
🧠 Learnings (16)
📚 Learning: in the codebase, `application.options.keybindings` uses the `application.window` type, whereas `appl...
Learnt from: nixpare
PR: wailsapp/wails#3763
File: v3/examples/keybindings/main.go:16-17
Timestamp: 2024-09-20T23:34:29.841Z
Learning: In the codebase, `application.Options.KeyBindings` uses the `application.Window` type, whereas `application.WebviewWindowOptions.KeyBindings` uses `*application.WebviewWindow`. This is intentional and acceptable.

Applied to files:

  • docs/src/content/docs/learn/application-menu.mdx
  • docs/src/content/docs/learn/context-menu.mdx
  • docs/src/content/docs/guides/customising-windows.mdx
  • docs/src/content/docs/learn/clipboard.mdx
  • docs/src/content/docs/learn/systray.mdx
  • docs/src/content/docs/tutorials/01-creating-a-service.mdx
  • docs/src/content/docs/guides/menus.mdx
  • docs/src/content/docs/learn/events.mdx
  • docs/src/content/docs/contributing/runtime-internals.mdx
  • docs/src/content/docs/contributing/codebase-layout.mdx
  • docs/src/content/docs/guides/gin-routing.mdx
  • docs/src/content/docs/whats-new.md
📚 Learning: the `keybindings` property of `application.option` uses the `application.window` type, while `applic...
Learnt from: nixpare
PR: wailsapp/wails#3763
File: v3/pkg/application/application_options.go:93-93
Timestamp: 2024-10-08T22:11:37.054Z
Learning: The `KeyBindings` property of `application.Option` uses the `application.Window` type, while `application.WebviewWindowOptions` still accepts `*application.WebviewWindow`, and this is intentional.

Applied to files:

  • docs/src/content/docs/learn/application-menu.mdx
  • docs/src/content/docs/guides/customising-windows.mdx
  • docs/src/content/docs/learn/clipboard.mdx
  • docs/src/content/docs/tutorials/01-creating-a-service.mdx
  • docs/src/content/docs/guides/menus.mdx
  • docs/src/content/docs/learn/events.mdx
  • docs/src/content/docs/contributing/runtime-internals.mdx
  • docs/src/content/docs/contributing/codebase-layout.mdx
  • docs/src/content/docs/guides/gin-routing.mdx
  • docs/src/content/docs/whats-new.md
📚 Learning: in `v3/examples/window/main.go`, `time.sleep` is used within a goroutine and does not block the ui t...
Learnt from: leaanthony
PR: wailsapp/wails#3763
File: v3/examples/window/main.go:472-475
Timestamp: 2024-10-08T22:11:37.054Z
Learning: In `v3/examples/window/main.go`, `time.Sleep` is used within a goroutine and does not block the UI thread.

Applied to files:

  • docs/src/content/docs/learn/application-menu.mdx
  • docs/src/content/docs/learn/context-menu.mdx
  • docs/src/content/docs/learn/clipboard.mdx
  • docs/src/content/docs/learn/systray.mdx
  • docs/src/content/docs/tutorials/01-creating-a-service.mdx
  • docs/src/content/docs/guides/file-associations.mdx
  • docs/src/content/docs/learn/events.mdx
  • docs/src/content/docs/contributing/runtime-internals.mdx
  • docs/src/content/docs/guides/gin-routing.mdx
  • docs/src/content/docs/whats-new.md
  • docs/src/content/docs/guides/events-reference.mdx
📚 Learning: in this codebase, typedefs for window references (like replacing `void *` with `windowref`) are not ...
Learnt from: nixpare
PR: wailsapp/wails#3763
File: v3/pkg/application/webview_window_bindings_darwin.h:0-0
Timestamp: 2024-09-21T13:34:24.145Z
Learning: In this codebase, typedefs for window references (like replacing `void *` with `WindowRef`) are not preferred; using `void *` is acceptable.

Applied to files:

  • docs/src/content/docs/learn/application-menu.mdx
  • docs/src/content/docs/guides/customising-windows.mdx
  • docs/src/content/docs/learn/clipboard.mdx
  • docs/src/content/docs/contributing/runtime-internals.mdx
  • docs/src/content/docs/contributing/codebase-layout.mdx
📚 Learning: in the wails menu system (v3/pkg/application/menu.go), shared state between menus is intentionally d...
Learnt from: leaanthony
PR: wailsapp/wails#4031
File: v3/pkg/application/menu.go:199-202
Timestamp: 2025-01-24T22:41:18.566Z
Learning: In the Wails menu system (v3/pkg/application/menu.go), shared state between menus is intentionally designed and desirable. Methods like `Append()` and `Prepend()` should maintain shared references to menu items rather than creating deep copies.

Applied to files:

  • docs/src/content/docs/learn/application-menu.mdx
  • docs/src/content/docs/learn/context-menu.mdx
  • docs/src/content/docs/learn/clipboard.mdx
  • docs/src/content/docs/learn/systray.mdx
  • docs/src/content/docs/learn/browser.mdx
  • docs/src/content/docs/guides/menus.mdx
  • docs/src/content/docs/learn/events.mdx
  • docs/src/content/docs/whats-new.md
📚 Learning: in `docs/src/content/docs/api/events_mac.md`, the heading levels are intentionally adjusted to impro...
Learnt from: stavros-k
PR: wailsapp/wails#3917
File: docs/src/content/docs/api/events_mac.md:9-9
Timestamp: 2024-12-02T22:13:32.421Z
Learning: In `docs/src/content/docs/api/events_mac.md`, the heading levels are intentionally adjusted to improve sizing on the browser, to avoid manually customizing the styling of the doc generator.

Applied to files:

  • docs/src/content/docs/learn/screens.mdx
  • docs/src/content/docs/guides/customising-windows.mdx
  • docs/src/content/docs/learn/environment.mdx
  • docs/src/content/docs/guides/menus.mdx
  • docs/src/content/docs/learn/events.mdx
  • docs/src/content/docs/contributing/codebase-layout.mdx
📚 Learning: in wails services (like ginservice), initializing the app field in servicestartup rather than in the...
Learnt from: leaanthony
PR: wailsapp/wails#4128
File: v3/examples/gin-service/services/gin_service.go:67-85
Timestamp: 2025-04-18T05:57:34.711Z
Learning: In Wails services (like GinService), initializing the app field in ServiceStartup rather than in the constructor is an acceptable pattern, as ServiceStartup is guaranteed to be called before any HTTP requests are handled.

Applied to files:

  • docs/src/content/docs/guides/custom-protocol-association.mdx
  • docs/src/content/docs/guides/gin-services.mdx
  • docs/src/content/docs/guides/gin-routing.mdx
  • docs/src/content/docs/guides/events-reference.mdx
📚 Learning: in the notifications package, initialization of the `service` struct is handled through platform-spe...
Learnt from: popaprozac
PR: wailsapp/wails#4098
File: v3/pkg/services/notifications/notifications.go:46-55
Timestamp: 2025-03-24T20:22:56.233Z
Learning: In the notifications package, initialization of the `Service` struct is handled through platform-specific `New()` functions in each implementation file (darwin, windows, linux) rather than a generic constructor in the main package file.

Applied to files:

  • docs/src/content/docs/tutorials/01-creating-a-service.mdx
📚 Learning: in the notifications package, initialization of the `service` struct is handled through platform-spe...
Learnt from: popaprozac
PR: wailsapp/wails#4098
File: v3/pkg/services/notifications/notifications.go:46-55
Timestamp: 2025-03-24T20:22:56.233Z
Learning: In the notifications package, initialization of the `Service` struct is handled through platform-specific `New()` functions in each implementation file (darwin, windows, linux) rather than a generic constructor in the main package file. Each platform implementation follows a singleton pattern using `notificationServiceOnce.Do()` and creates a global `NotificationService` variable that's accessed through a thread-safe `getNotificationService()` function.

Applied to files:

  • docs/src/content/docs/tutorials/01-creating-a-service.mdx
📚 Learning: in the wails documentation, all content under 'docs/src/content/docs' is accessible at the root path...
Learnt from: stavros-k
PR: wailsapp/wails#3917
File: docs/astro.config.mjs:0-0
Timestamp: 2024-12-02T22:00:10.339Z
Learning: In the Wails documentation, all content under 'docs/src/content/docs' is accessible at the root path '/', so links in the sidebar configuration should not include the '/docs' prefix.

Applied to files:

  • docs/src/content/docs/guides/menus.mdx
📚 Learning: in wails v2, unlike v3-alpha which has a `serviceshutdown` method for services, there is no standard...
Learnt from: popaprozac
PR: wailsapp/wails#4256
File: v2/internal/frontend/desktop/linux/notifications.go:27-28
Timestamp: 2025-04-29T23:54:07.488Z
Learning: In Wails v2, unlike v3-alpha which has a `ServiceShutdown` method for services, there is no standardized teardown pattern for frontend implementations. When implementing features that require cleanup (like goroutines or resources), add explicit cleanup methods (e.g., `CleanupNotifications()`) that handle resource release, context cancellation, and connection closure.

Applied to files:

  • docs/src/content/docs/guides/gin-services.mdx
  • docs/src/content/docs/guides/gin-routing.mdx
  • docs/src/content/docs/whats-new.md
  • docs/src/content/docs/guides/events-reference.mdx
📚 Learning: in the wails v3 codebase, panic is used to catch invalid invocations that should never occur in prod...
Learnt from: fbbdev
PR: wailsapp/wails#4024
File: v3/pkg/application/services.go:38-51
Timestamp: 2025-01-18T21:19:47.778Z
Learning: In the Wails v3 codebase, panic is used to catch invalid invocations that should never occur in production (programming errors), while error returns are reserved for recoverable error conditions (runtime errors). For example, the `NewService` function in `v3/pkg/application/services.go` uses panic to handle the case where more than one `ServiceOptions` instance is provided, as this is considered an unrecoverable programming error.

Applied to files:

  • docs/src/content/docs/guides/gin-services.mdx
📚 Learning: in the wails v3 project, internal functions are designed to panic on nil parameters as they represen...
Learnt from: fbbdev
PR: wailsapp/wails#4045
File: v3/internal/generator/render/info.go:28-68
Timestamp: 2025-02-04T23:59:43.956Z
Learning: In the Wails v3 project, internal functions are designed to panic on nil parameters as they represent contract violations, rather than adding defensive nil checks.

Applied to files:

  • docs/src/content/docs/guides/gin-services.mdx
  • docs/src/content/docs/guides/gin-routing.mdx
📚 Learning: the `//wails:inject` directive in wails enables custom code injection, allowing methods like `custom...
Learnt from: fbbdev
PR: wailsapp/wails#4045
File: v3/internal/generator/testcases/directives/otherpackage/js/test_t.ts:1-3
Timestamp: 2025-02-05T11:53:45.812Z
Learning: The `//wails:inject` directive in Wails enables custom code injection, allowing methods like `CustomMethod` to be injected and used in JavaScript/TypeScript files without being explicitly defined in a service.js file.

Applied to files:

  • docs/src/content/docs/guides/gin-services.mdx
📚 Learning: error handling is not required in example code within the wails repository as examples should priori...
Learnt from: leaanthony
PR: wailsapp/wails#4013
File: v3/examples/contextmenus/main.go:38-44
Timestamp: 2025-01-17T05:51:02.521Z
Learning: Error handling is not required in example code within the Wails repository as examples should prioritize clarity and simplicity over production-level concerns.

Applied to files:

  • docs/src/content/docs/guides/gin-services.mdx
  • docs/src/content/docs/guides/gin-routing.mdx
📚 Learning: in wails applications, it's not necessary to implement explicit graceful shutdown for simple gorouti...
Learnt from: leaanthony
PR: wailsapp/wails#4234
File: v3/examples/badge-custom/main.go:87-93
Timestamp: 2025-04-26T21:03:42.481Z
Learning: In Wails applications, it's not necessary to implement explicit graceful shutdown for simple goroutines (like time emitters) as Go automatically terminates all goroutines as part of the application shutdown process.

Applied to files:

  • docs/src/content/docs/guides/gin-routing.mdx
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (1)
  • GitHub Check: semgrep-cloud-platform/scan
🔇 Additional comments (15)
docs/src/content/docs/getting-started/installation.mdx (1)

20-23: Go version bump confirmed

All v3 modules declare go 1.24 (or higher), so updating the docs to require Go 1.24 is correct. No further changes are needed.

docs/src/content/docs/guides/custom-protocol-association.mdx (1)

71-77: Double-check new Event manager API names
The snippet uses app.Event.OnApplicationEvent and app.Event.Emit. If the new manager follows the same naming conventions used elsewhere (On, Emit, etc.), these method names might differ (e.g. app.Event.On, app.Event.Emit).

Please verify the actual exported names in pkg/application/eventmanager.go and adjust the docs to avoid compile-time errors for readers copy-pasting the example.

docs/src/content/docs/learn/environment.mdx (3)

90-107: Event-manager accessor is correct & matches v3 API

The example now uses app.Event.OnApplicationEvent, which is the correct accessor after the Manager refactor. Handler signature and import are also in line with current application.ApplicationEvent API.
No further action required.


402-407: Consistent update across Best-Practices snippet

The same accessor change is applied here and keeps the code in sync with the earlier snippet—nice catch keeping the docs consistent.


499-508: Function-level example updated correctly

monitorThemeChanges now routes through app.Event as expected. Implementation remains accurate.

docs/src/content/docs/learn/screens.mdx (2)

395-402: Screen-change listener reflects new API

app.Event.OnApplicationEvent(events.Common.SystemDisplayChanged, …) is the right call after refactor. Example remains compile-ready.


485-496: Duplicate listener update looks good

Second occurrence of the screen-change handler is updated consistently. 👍

docs/src/content/docs/contributing/codebase-layout.mdx (1)

119-124: Verify expected argument type for Window.New

Older examples used Window.NewWithOptions(opts) while this snippet passes a pointer to Window.New(&opts).
If Window.New(*application.WebviewWindowOptions) actually expects a value (not a pointer) or the method name is still NewWithOptions, this example will not compile.

-window := app.Window.New(&application.WebviewWindowOptions{
+window := app.Window.New(application.WebviewWindowOptions{

Please confirm the current signature and adjust to avoid reader confusion.

docs/src/content/docs/tutorials/01-creating-a-service.mdx (1)

84-88: Compilation-ready: confirm struct-value vs pointer

Window.NewWithOptions(application.WebviewWindowOptions{…}) usually expects a pointer to options in the runtime code. Double-check the signature; if it wants *application.WebviewWindowOptions, prepend &.

-app.Window.NewWithOptions(application.WebviewWindowOptions{
+app.Window.NewWithOptions(&application.WebviewWindowOptions{

Ensures the tutorial builds out-of-the-box.

docs/src/content/docs/guides/file-associations.mdx (1)

72-93: End-to-end example almost perfect – minor dialog API check

Great job expanding the snippet and updating to app.Event.OnApplicationEvent.
Small thing: application.InfoDialog() is used instead of the more common app.Dialog.Info(). If InfoDialog() really is a package-level helper that returns a dialog builder, all good; otherwise switch to the instance method so the code compiles.

-application.InfoDialog().SetMessage("Application opened with file: " + associatedFile).Show()
+app.Dialog.Info().SetMessage("Application opened with file: " + associatedFile).Show()
docs/src/content/docs/learn/browser.mdx (1)

243-245: Verify Env accessor – API may still be Environment

The code changed from app.Environment.Info().Debug to app.Env.Info().Debug.
Double-check the latest application.App API; if Env does not exist this snippet will not compile.

docs/src/content/docs/learn/systray.mdx (1)

127-135: Prefer app.Menu.New() consistently

Nice alignment with the new Manager API. No issues here.

docs/src/content/docs/learn/events.mdx (2)

16-28: Good migration to Event manager

Listener registration reflects the new API correctly. 👍


517-529: WebView event constants require platform separation

Similar to the menu section, wrap macOS/Windows-specific examples in build-tags or comments to prevent compile errors on the wrong OS.

docs/src/content/docs/learn/context-menu.mdx (1)

211-215: API update looks correct

The switch from app.NewWebviewWindow() to app.Window.New() is consistent with the new Manager‐based API and the returned handle is immediately used, so the snippet compiles as-is.

Comment thread docs/src/content/docs/guides/events-reference.mdx
Comment thread docs/src/content/docs/guides/gin-services.mdx
Comment thread docs/src/content/docs/learn/events.mdx Outdated
@yulesxoxo yulesxoxo changed the title v3 update docs to reflect changes from Manager API Refactoring [v3] update docs to reflect changes from Manager API Refactoring Aug 4, 2025
@sonarqubecloud

sonarqubecloud Bot commented Aug 5, 2025

Copy link
Copy Markdown

@dosubot dosubot Bot added the lgtm This PR has been approved by a maintainer label Aug 5, 2025
@leaanthony

Copy link
Copy Markdown
Member

Absolute legend! 👌

@leaanthony leaanthony merged commit c02ba8f into wailsapp:v3-alpha Aug 5, 2025
61 checks passed
Grantmartin2002 pushed a commit to Grantmartin2002/wails that referenced this pull request Apr 29, 2026
…lsapp#4476)

* (docs) installation.mdx: update required Go version to 1.24

* (docs) update for Manager API Refactoring wailsapp#4359

* add entry in UNRELEASED_CHANGELOG.md to satisfy github actions

* thx coderabbitai

* thx coderabbitai
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Documentation Improvements or additions to documentation lgtm This PR has been approved by a maintainer size:L This PR changes 100-499 lines, ignoring generated files. v3-alpha

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants