advanced bindings documentation#4404
Merged
Merged
Conversation
Contributor
## Walkthrough
This update introduces three new documentation files to the Wails v3 docs: one on advanced binding techniques, one on binding best practices, and one explaining the binding system internals. Additionally, a minor correction is made to an example in the existing bindings documentation by removing an unnecessary function call.
## Changes
| File(s) | Change Summary |
|---------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------|
| docs/src/content/docs/learn/advanced-binding.mdx | Added comprehensive documentation on advanced binding customization, directives, complex type handling, and optimizations. |
| docs/src/content/docs/learn/binding-best-practices.mdx | Added guide outlining recommended usage patterns and best practices for the Wails binding system. |
| docs/src/content/docs/learn/binding-system.mdx | Added documentation explaining the architecture and internals of the Wails binding system, including type mapping and directives. |
| docs/src/content/docs/learn/bindings.mdx | Removed a redundant function call from an example and added a trailing newline. |
| docs/src/content/docs/changelog.mdx | Updated changelog to include entry for the new bindings guide contribution. |
## Sequence Diagram(s)
```mermaid
sequenceDiagram
participant GoCode as Go Code (with directives)
participant BindingGenerator as Binding Generator
participant JS_TS as Generated JS/TS Bindings
participant Docs as Documentation
GoCode->>BindingGenerator: Parse code and directives (inject, include, internal, ignore, id)
BindingGenerator->>BindingGenerator: Analyze types and methods
BindingGenerator->>JS_TS: Generate bindings (apply directives, map types)
BindingGenerator->>Docs: Output documentation and examplesPossibly related PRs
Suggested reviewers
Poem
|
Contributor
There was a problem hiding this comment.
Actionable comments posted: 0
🧹 Nitpick comments (7)
docs/src/content/docs/learn/binding-best-practices.mdx (3)
42-50: Add missing import fortimeto keep the snippet compilable
The example struct usestime.Timebut the snippet omits theimport "time"statement. Readers copying the code will hit a compile error.type User struct { + // import "time" is required above for these fields ID int `json:"id"`
94-102: Includecontextimport in the cancellation example
ctxcomes from the standard library’scontextpackage, but the snippet doesn’t show the import, making it non-self-contained.-func (s *ProductService) GetProducts(ctx context.Context, req ProductsRequest) (ProductsResponse, error) { +import "context" + +func (s *ProductService) GetProducts(ctx context.Context, req ProductsRequest) (ProductsResponse, error) {
58-85: Explicitly highlight data-exposure intent when converting toUserDTO
You already dropPassword,UpdatedAt, etc., but stating that the DTO is intentionally minimal helps readers understand why two models exist.Consider adding a short comment above the
UserDTOdeclaration, e.g.// UserDTO is the pared-down version sent to the frontend – never expose secrets!docs/src/content/docs/learn/binding-system.mdx (2)
68-76: Warn about 64-bit integers exceeding JS safe range
uint64/int64map tonumber, but JS numbers are IEEE-754 doubles with only 53 bits of integer precision. Mentioning this pitfall would save users surprise data loss.| `int64`, `uint64` | `number`* | `number`* | \* Values larger than 2^53-1 lose precision in JavaScript – prefer `string` or `bigint` if you need full 64-bit accuracy.
82-93: Minor punctuation tidy-up in directive list
The dash before each directive is already bullet syntax; the extra “:” after the item results in an odd pause when read aloud.- - `//wails:inject`: Injects custom JavaScript/TypeScript code into the generated bindings + - `//wails:inject` – Inject custom JavaScript/TypeScript code into the generated bindingsdocs/src/content/docs/learn/advanced-binding.mdx (2)
40-44: Clarify path base for//wails:includeexample
The example//wails:include js/*.jsimplicitly uses a path relative to the Go package of the directive.
Adding a short note avoids confusion for users expecting project-root semantics.//wails:include js/*.js // path is relative to the *current Go package*
18-24: Demonstrate language-scoped injection even in the first example
Because//wails:injectwithout a scope injects into all outputs, many users accidentally pollute their TS builds with plain JS snippets. Showing the scoped variant first reduces that risk.-//wails:inject console.log("Hello from Wails!"); +//wails:inject j*:console.log("Hello from Wails!");
📜 Review details
Configuration used: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
⛔ Files ignored due to path filters (1)
docs/package-lock.jsonis excluded by!**/package-lock.json
📒 Files selected for processing (4)
docs/src/content/docs/learn/advanced-binding.mdx(1 hunks)docs/src/content/docs/learn/binding-best-practices.mdx(1 hunks)docs/src/content/docs/learn/binding-system.mdx(1 hunks)docs/src/content/docs/learn/bindings.mdx(1 hunks)
🧰 Additional context used
🧠 Learnings (5)
📓 Common learnings
Learnt from: fbbdev
PR: wailsapp/wails#4001
File: v3/internal/generator/testdata/output/lang=TS/UseInterfaces=true/UseNames=false/github.com/wailsapp/wails/v3/internal/generator/testcases/function_single_internal/greetservice.ts:0-0
Timestamp: 2025-01-15T22:33:30.639Z
Learning: In the Wails framework's TypeScript bindings, the import path "/wails/runtime.js" is intentionally absolute and should not be changed to a relative 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.
docs/src/content/docs/learn/bindings.mdx (6)
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.
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.
Learnt from: leaanthony
PR: wailsapp/wails#3763
File: v3/examples/window/main.go:472-475
Timestamp: 2024-09-30T06:13:46.595Z
Learning: In `v3/examples/window/main.go`, `time.Sleep` is used within a goroutine and does not block the UI thread.
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.
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.
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.
docs/src/content/docs/learn/binding-best-practices.mdx (5)
Learnt from: stavros-k
PR: wailsapp/wails#3917
File: docs/src/content/docs/index.mdx:13-18
Timestamp: 2024-12-02T22:14:41.158Z
Learning: The documentation page `/learn/services` exists in `docs/src/content/docs/learn/services.md`.
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.
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.
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.
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.
docs/src/content/docs/learn/binding-system.mdx (3)
Learnt from: fbbdev
PR: wailsapp/wails#4045
File: v3/internal/generator/render/templates/index.tmpl:37-37
Timestamp: 2025-02-05T11:53:01.219Z
Learning: The template `v3/internal/generator/render/templates/index.tmpl` relies on models being sorted with exported ones first, which enables breaking early when encountering non-exported models. This contract needs to be verified and documented in the codebase.
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.
Learnt from: fbbdev
PR: wailsapp/wails#4001
File: v3/internal/generator/testdata/output/lang=TS/UseInterfaces=true/UseNames=false/github.com/wailsapp/wails/v3/internal/generator/testcases/function_single_internal/greetservice.ts:0-0
Timestamp: 2025-01-15T22:33:30.639Z
Learning: In the Wails framework's TypeScript bindings, the import path "/wails/runtime.js" is intentionally absolute and should not be changed to a relative path.
docs/src/content/docs/learn/advanced-binding.mdx (4)
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.
Learnt from: fbbdev
PR: wailsapp/wails#4001
File: v3/internal/generator/testdata/output/lang=TS/UseInterfaces=true/UseNames=false/github.com/wailsapp/wails/v3/internal/generator/testcases/function_single_internal/greetservice.ts:0-0
Timestamp: 2025-01-15T22:33:30.639Z
Learning: In the Wails framework's TypeScript bindings, the import path "/wails/runtime.js" is intentionally absolute and should not be changed to a relative path.
Learnt from: stavros-k
PR: wailsapp/wails#3917
File: docs/src/content/docs/index.mdx:13-18
Timestamp: 2024-12-02T22:14:41.158Z
Learning: The documentation page `/learn/services` exists in `docs/src/content/docs/learn/services.md`.
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.
🪛 LanguageTool
docs/src/content/docs/learn/binding-system.mdx
[uncategorized] ~88-~88: Loose punctuation mark.
Context: ...Available Directives - //wails:inject: Injects custom JavaScript/TypeScript co...
(UNLIKELY_OPENING_PUNCTUATION)
[style] ~91-~91: Consider using a different adverb to strengthen your wording.
Context: ...ted to the frontend - //wails:ignore: Completely ignores a method during binding generat...
(COMPLETELY_ENTIRELY)
[style] ~116-~116: To form a complete sentence, be sure to include a subject.
Context: ... - t - TypeScript only - <style> can be: - * - Both classes and interfac...
(MISSING_IT_THERE)
docs/src/content/docs/learn/advanced-binding.mdx
[style] ~64-~64: Consider using a different adverb to strengthen your wording.
Context: ...Methods The //wails:ignore directive completely ignores a method during binding generat...
(COMPLETELY_ENTIRELY)
[style] ~71-~71: Consider using a different adverb to strengthen your wording.
Context: ...s similar to //wails:internal, but it completely ignores the method rather than marking ...
(COMPLETELY_ENTIRELY)
🔇 Additional comments (1)
docs/src/content/docs/learn/bindings.mdx (1)
674-674: Only newline appended – nothing to review
This hunk just adds a trailing newline after the:::cautionblock. No action required.
leaanthony
approved these changes
Jul 11, 2025
Member
|
You nuclear-grade legend! 🙏 |
|
15 tasks
Grantmartin2002
pushed a commit
to Grantmartin2002/wails
that referenced
this pull request
Apr 29, 2026
* advanced bindings documentation * update changelog --------- Co-authored-by: Lea Anthony <lea.anthony@gmail.com>
This was referenced May 6, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary by CodeRabbit