diff --git a/docs/astro.config.mjs b/docs/astro.config.mjs
index ecac07011..ac306b8a7 100644
--- a/docs/astro.config.mjs
+++ b/docs/astro.config.mjs
@@ -266,41 +266,13 @@ export default defineConfig({
collapsed: true,
items: [
{ label: "Overview", link: "/reference/overview" },
- {
- label: "Application",
- collapsed: true,
- autogenerate: { directory: "reference/application" },
- },
- {
- label: "Window",
- collapsed: true,
- autogenerate: { directory: "reference/window" },
- },
- {
- label: "Menu",
- collapsed: true,
- autogenerate: { directory: "reference/menu" },
- },
- {
- label: "Events",
- collapsed: true,
- autogenerate: { directory: "reference/events" },
- },
- {
- label: "Dialogs",
- collapsed: true,
- autogenerate: { directory: "reference/dialogs" },
- },
- {
- label: "Runtime",
- collapsed: true,
- autogenerate: { directory: "reference/runtime" },
- },
- {
- label: "CLI",
- collapsed: true,
- autogenerate: { directory: "reference/cli" },
- },
+ { label: "Application", link: "/reference/application" },
+ { label: "Window", link: "/reference/window" },
+ { label: "Menu", link: "/reference/menu" },
+ { label: "Events", link: "/reference/events" },
+ { label: "Dialogs", link: "/reference/dialogs" },
+ { label: "Frontend Runtime", link: "/reference/frontend-runtime" },
+ { label: "CLI", link: "/reference/cli" },
],
},
diff --git a/docs/src/content/docs/index.mdx b/docs/src/content/docs/index.mdx
index 7d10e0a97..eb1f6693e 100644
--- a/docs/src/content/docs/index.mdx
+++ b/docs/src/content/docs/index.mdx
@@ -277,7 +277,7 @@ cd myapp && wails3 dev
## Next Steps
-Next: [Build a complete application](/tutorials/03-notes-vanilla), browse [examples](https://github.com/wailsapp/wails/tree/v3-alpha/v3/examples), or check the [API reference](/reference/application-api). Migrating from v2? See the [upgrade guide](/migration/v2-to-v3).
+Next: [Build a complete application](/tutorials/03-notes-vanilla), browse [examples](https://github.com/wailsapp/wails/tree/v3-alpha/v3/examples), or check the [API reference](/reference/application). Migrating from v2? See the [upgrade guide](/migration/v2-to-v3).
:::note[Production Ready]
diff --git a/docs/src/content/docs/reference/application-api.mdx b/docs/src/content/docs/reference/application.mdx
similarity index 74%
rename from docs/src/content/docs/reference/application-api.mdx
rename to docs/src/content/docs/reference/application.mdx
index e74a00122..ed87725c1 100644
--- a/docs/src/content/docs/reference/application-api.mdx
+++ b/docs/src/content/docs/reference/application.mdx
@@ -389,103 +389,30 @@ import (
"github.com/wailsapp/wails/v3/pkg/application"
)
-type App struct {
- app *application.Application
-}
-
-func NewApp(app *application.Application) *App {
- return &App{app: app}
-}
-
-func (a *App) Startup() {
- // Listen for events
- a.app.OnEvent("data-updated", func(e *application.CustomEvent) {
- a.app.Logger.Info("Data updated", "data", e.Data)
- })
-
- // Listen for shutdown
- a.app.OnApplicationEvent(application.EventApplicationShutdown, func(e *application.ApplicationEvent) {
- a.app.Logger.Info("Shutting down")
- // Cleanup
- })
-}
-
-func (a *App) ShowMessage(message string) {
- a.app.InfoDialog().
- SetTitle("Message").
- SetMessage(message).
- Show()
-}
-
-func (a *App) GetData() string {
- // Get clipboard
- text, _ := a.app.Clipboard.Text()
- return text
-}
-
func main() {
app := application.New(application.Options{
- Name: "My App",
- Services: []application.Service{
- application.NewService(NewApp(app)),
+ Name: "My Application",
+ Description: "A demo application",
+ Mac: application.MacOptions{
+ ApplicationShouldTerminateAfterLastWindowClosed: true,
},
})
-
- app.NewWebviewWindowWithOptions(application.WebviewWindowOptions{
- Title: "My App",
- Width: 800,
- Height: 600,
+
+ // Create main window
+ window := app.NewWebviewWindowWithOptions(application.WebviewWindowOptions{
+ Title: "My App",
+ Width: 1024,
+ Height: 768,
+ MinWidth: 800,
+ MinHeight: 600,
+ BackgroundColour: application.NewRGB(255, 255, 255),
+ URL: "http://wails.localhost/",
})
-
+
+ window.Centre()
+ window.Show()
+
app.Run()
}
```
-## Best Practices
-
-### ✅ Do
-
-- **Store app reference** - Keep in service structs
-- **Use managers** - Access features through managers
-- **Handle errors** - Check dialog results
-- **Use logger** - Structured logging
-- **Clean up** - Use shutdown hooks
-
-### ❌ Don't
-
-- **Don't block Run()** - It's the event loop
-- **Don't ignore errors** - Handle all errors
-- **Don't create multiple apps** - One per process
-- **Don't call Quit() in startup** - Let app initialize
-
-## Next Steps
-
-
-
- Complete window management reference.
-
- [Learn More →](/reference/window-api)
-
-
-
- Learn about service architecture.
-
- [Learn More →](/features/bindings/services)
-
-
-
- Master the event system.
-
- [Learn More →](/features/events/system)
-
-
-
- Use native dialogs.
-
- [Learn More →](/features/dialogs/overview)
-
-
-
----
-
-**Questions?** Ask in [Discord](https://discord.gg/JDdSxwjhGf) or check the [examples](https://github.com/wailsapp/wails/tree/v3-alpha/v3/examples).
diff --git a/docs/src/content/docs/reference/cli.mdx b/docs/src/content/docs/reference/cli.mdx
new file mode 100644
index 000000000..9f37ff6bf
--- /dev/null
+++ b/docs/src/content/docs/reference/cli.mdx
@@ -0,0 +1,28 @@
+---
+title: CLI Reference
+description: Complete reference for the Wails CLI commands
+sidebar:
+ order: 1
+---
+
+## Overview
+
+The Wails CLI (`wails3`) provides commands for creating, developing, building, and managing Wails applications.
+
+## Coming Soon
+
+This section is under construction. For now, use `wails3 --help` or `wails3 [command] --help` for command documentation.
+
+**Common commands:**
+
+```bash
+wails3 init # Create a new project
+wails3 dev # Run in development mode
+wails3 build # Build for production
+wails3 generate # Generate bindings or runtime
+wails3 doctor # Check development environment
+```
+
+---
+
+**Questions?** Ask in [Discord](https://discord.gg/JDdSxwjhGf) or check the [examples](https://github.com/wailsapp/wails/tree/v3-alpha/v3/examples).
diff --git a/docs/src/content/docs/reference/dialogs.mdx b/docs/src/content/docs/reference/dialogs.mdx
new file mode 100644
index 000000000..90766b390
--- /dev/null
+++ b/docs/src/content/docs/reference/dialogs.mdx
@@ -0,0 +1,791 @@
+---
+title: Dialogs API
+description: Complete reference for native dialog APIs
+sidebar:
+ order: 5
+---
+
+import { Card, CardGrid } from "@astrojs/starlight/components";
+
+## Overview
+
+The Dialogs API provides methods to show native file dialogs and message dialogs.
+
+**Dialog Types:**
+- **File Dialogs** - Open, Save, and Select Folder dialogs
+- **Message Dialogs** - Info, Error, Warning, and Question dialogs
+
+All dialogs are **native OS dialogs** that match the platform's look and feel.
+
+## File Dialogs
+
+### OpenFileDialog()
+
+Creates a file open dialog.
+
+```go
+func (a *App) OpenFileDialog() *OpenFileDialog
+```
+
+**Example:**
+```go
+dialog := app.OpenFileDialog()
+```
+
+### OpenFileDialog Methods
+
+#### SetTitle()
+
+Sets the dialog title.
+
+```go
+func (d *OpenFileDialog) SetTitle(title string) *OpenFileDialog
+```
+
+**Example:**
+```go
+dialog.SetTitle("Select Image")
+```
+
+#### SetFilters()
+
+Sets file type filters.
+
+```go
+func (d *OpenFileDialog) SetFilters(filters []FileFilter) *OpenFileDialog
+```
+
+**FileFilter structure:**
+```go
+type FileFilter struct {
+ DisplayName string // "Images", "Documents", etc.
+ Pattern string // "*.png;*.jpg", "*.pdf;*.doc", etc.
+}
+```
+
+**Example:**
+```go
+dialog.SetFilters([]application.FileFilter{
+ {DisplayName: "Images", Pattern: "*.png;*.jpg;*.gif"},
+ {DisplayName: "Documents", Pattern: "*.pdf;*.docx"},
+ {DisplayName: "All Files", Pattern: "*.*"},
+})
+```
+
+#### SetDefaultDirectory()
+
+Sets the initial directory.
+
+```go
+func (d *OpenFileDialog) SetDefaultDirectory(path string) *OpenFileDialog
+```
+
+**Example:**
+```go
+homeDir, _ := os.UserHomeDir()
+dialog.SetDefaultDirectory(homeDir)
+```
+
+#### PromptForSingleSelection()
+
+Shows the dialog and returns the selected file.
+
+```go
+func (d *OpenFileDialog) PromptForSingleSelection() (string, error)
+```
+
+**Returns:**
+- `string` - Selected file path
+- `error` - Error if cancelled or failed
+
+**Example:**
+```go
+path, err := app.OpenFileDialog().
+ SetTitle("Select Image").
+ SetFilters([]application.FileFilter{
+ {DisplayName: "Images", Pattern: "*.png;*.jpg;*.gif"},
+ }).
+ PromptForSingleSelection()
+
+if err != nil {
+ // User cancelled or error occurred
+ return
+}
+
+// Use the selected file
+processFile(path)
+```
+
+#### PromptForMultipleSelection()
+
+Shows the dialog and returns multiple selected files.
+
+```go
+func (d *OpenFileDialog) PromptForMultipleSelection() ([]string, error)
+```
+
+**Returns:**
+- `[]string` - Array of selected file paths
+- `error` - Error if cancelled or failed
+
+**Example:**
+```go
+paths, err := app.OpenFileDialog().
+ SetTitle("Select Images").
+ SetFilters([]application.FileFilter{
+ {DisplayName: "Images", Pattern: "*.png;*.jpg"},
+ }).
+ PromptForMultipleSelection()
+
+if err != nil {
+ return
+}
+
+for _, path := range paths {
+ processFile(path)
+}
+```
+
+### SaveFileDialog()
+
+Creates a file save dialog.
+
+```go
+func (a *App) SaveFileDialog() *SaveFileDialog
+```
+
+**Example:**
+```go
+dialog := app.SaveFileDialog()
+```
+
+### SaveFileDialog Methods
+
+#### SetTitle()
+
+Sets the dialog title.
+
+```go
+func (d *SaveFileDialog) SetTitle(title string) *SaveFileDialog
+```
+
+#### SetDefaultFilename()
+
+Sets the default filename.
+
+```go
+func (d *SaveFileDialog) SetDefaultFilename(filename string) *SaveFileDialog
+```
+
+**Example:**
+```go
+dialog.SetDefaultFilename("document.pdf")
+```
+
+#### SetFilters()
+
+Sets file type filters (same as OpenFileDialog).
+
+```go
+func (d *SaveFileDialog) SetFilters(filters []FileFilter) *SaveFileDialog
+```
+
+#### SetDefaultDirectory()
+
+Sets the initial directory (same as OpenFileDialog).
+
+```go
+func (d *SaveFileDialog) SetDefaultDirectory(path string) *SaveFileDialog
+```
+
+#### PromptForSingleSelection()
+
+Shows the dialog and returns the save path.
+
+```go
+func (d *SaveFileDialog) PromptForSingleSelection() (string, error)
+```
+
+**Example:**
+```go
+path, err := app.SaveFileDialog().
+ SetTitle("Save Document").
+ SetDefaultFilename("untitled.pdf").
+ SetFilters([]application.FileFilter{
+ {DisplayName: "PDF Document", Pattern: "*.pdf"},
+ }).
+ PromptForSingleSelection()
+
+if err != nil {
+ // User cancelled
+ return
+}
+
+// Save to the selected path
+saveDocument(path)
+```
+
+### SelectFolderDialog()
+
+Creates a folder selection dialog.
+
+```go
+func (a *App) SelectFolderDialog() *SelectFolderDialog
+```
+
+**Example:**
+```go
+dialog := app.SelectFolderDialog()
+```
+
+### SelectFolderDialog Methods
+
+#### SetTitle()
+
+Sets the dialog title.
+
+```go
+func (d *SelectFolderDialog) SetTitle(title string) *SelectFolderDialog
+```
+
+#### SetDefaultDirectory()
+
+Sets the initial directory.
+
+```go
+func (d *SelectFolderDialog) SetDefaultDirectory(path string) *SelectFolderDialog
+```
+
+#### PromptForSingleSelection()
+
+Shows the dialog and returns the selected folder.
+
+```go
+func (d *SelectFolderDialog) PromptForSingleSelection() (string, error)
+```
+
+**Example:**
+```go
+path, err := app.SelectFolderDialog().
+ SetTitle("Select Output Folder").
+ PromptForSingleSelection()
+
+if err != nil {
+ // User cancelled
+ return
+}
+
+// Use the selected folder
+outputDir = path
+```
+
+## Message Dialogs
+
+### InfoDialog()
+
+Creates an information dialog.
+
+```go
+func (a *App) InfoDialog() *InfoDialog
+```
+
+**Example:**
+```go
+dialog := app.InfoDialog()
+```
+
+### InfoDialog Methods
+
+#### SetTitle()
+
+Sets the dialog title.
+
+```go
+func (d *InfoDialog) SetTitle(title string) *InfoDialog
+```
+
+#### SetMessage()
+
+Sets the dialog message.
+
+```go
+func (d *InfoDialog) SetMessage(message string) *InfoDialog
+```
+
+#### Show()
+
+Shows the dialog.
+
+```go
+func (d *InfoDialog) Show()
+```
+
+**Example:**
+```go
+app.InfoDialog().
+ SetTitle("Success").
+ SetMessage("File saved successfully!").
+ Show()
+```
+
+### ErrorDialog()
+
+Creates an error dialog.
+
+```go
+func (a *App) ErrorDialog() *ErrorDialog
+```
+
+**Methods:** Same as InfoDialog (SetTitle, SetMessage, Show)
+
+**Example:**
+```go
+app.ErrorDialog().
+ SetTitle("Error").
+ SetMessage("Failed to save file: " + err.Error()).
+ Show()
+```
+
+### WarningDialog()
+
+Creates a warning dialog.
+
+```go
+func (a *App) WarningDialog() *WarningDialog
+```
+
+**Methods:** Same as InfoDialog (SetTitle, SetMessage, Show)
+
+**Example:**
+```go
+app.WarningDialog().
+ SetTitle("Warning").
+ SetMessage("This action cannot be undone.").
+ Show()
+```
+
+### QuestionDialog()
+
+Creates a question dialog with custom buttons.
+
+```go
+func (a *App) QuestionDialog() *QuestionDialog
+```
+
+### QuestionDialog Methods
+
+#### SetTitle()
+
+Sets the dialog title.
+
+```go
+func (d *QuestionDialog) SetTitle(title string) *QuestionDialog
+```
+
+#### SetMessage()
+
+Sets the dialog message.
+
+```go
+func (d *QuestionDialog) SetMessage(message string) *QuestionDialog
+```
+
+#### SetButtons()
+
+Sets the button labels.
+
+```go
+func (d *QuestionDialog) SetButtons(buttons ...string) *QuestionDialog
+```
+
+**Parameters:**
+- `buttons` - Variable number of button labels
+
+**Example:**
+```go
+dialog.SetButtons("Yes", "No")
+dialog.SetButtons("Save", "Don't Save", "Cancel")
+```
+
+#### SetDefaultButton()
+
+Sets which button is the default (activated by pressing Enter).
+
+```go
+func (d *QuestionDialog) SetDefaultButton(index int) *QuestionDialog
+```
+
+**Example:**
+```go
+// Make "Yes" the default button
+dialog.SetButtons("Yes", "No").SetDefaultButton(0)
+```
+
+#### SetCancelButton()
+
+Sets which button is the cancel button (activated by pressing Escape).
+
+```go
+func (d *QuestionDialog) SetCancelButton(index int) *QuestionDialog
+```
+
+**Example:**
+```go
+// Make "Cancel" the cancel button
+dialog.SetButtons("Save", "Don't Save", "Cancel").SetCancelButton(2)
+```
+
+#### Show()
+
+Shows the dialog and returns the selected button.
+
+```go
+func (d *QuestionDialog) Show() (string, error)
+```
+
+**Returns:**
+- `string` - The label of the button that was clicked
+- `error` - Error if dialog failed to show
+
+**Example:**
+```go
+result, err := app.QuestionDialog().
+ SetTitle("Confirm").
+ SetMessage("Do you want to save changes?").
+ SetButtons("Save", "Don't Save", "Cancel").
+ SetDefaultButton(0).
+ SetCancelButton(2).
+ Show()
+
+if err != nil {
+ return
+}
+
+switch result {
+case "Save":
+ saveDocument()
+case "Don't Save":
+ // Continue without saving
+case "Cancel":
+ return
+}
+```
+
+## Complete Examples
+
+### File Selection Example
+
+```go
+type FileService struct {
+ app *application.Application
+}
+
+func (s *FileService) OpenImage() (string, error) {
+ path, err := s.app.OpenFileDialog().
+ SetTitle("Select Image").
+ SetFilters([]application.FileFilter{
+ {DisplayName: "Images", Pattern: "*.png;*.jpg;*.jpeg;*.gif"},
+ {DisplayName: "All Files", Pattern: "*.*"},
+ }).
+ PromptForSingleSelection()
+
+ if err != nil {
+ return "", err
+ }
+
+ return path, nil
+}
+
+func (s *FileService) SaveDocument(defaultName string) (string, error) {
+ path, err := s.app.SaveFileDialog().
+ SetTitle("Save Document").
+ SetDefaultFilename(defaultName).
+ SetFilters([]application.FileFilter{
+ {DisplayName: "PDF Document", Pattern: "*.pdf"},
+ {DisplayName: "Text Document", Pattern: "*.txt"},
+ }).
+ PromptForSingleSelection()
+
+ if err != nil {
+ return "", err
+ }
+
+ return path, nil
+}
+
+func (s *FileService) SelectOutputFolder() (string, error) {
+ path, err := s.app.SelectFolderDialog().
+ SetTitle("Select Output Folder").
+ PromptForSingleSelection()
+
+ if err != nil {
+ return "", err
+ }
+
+ return path, nil
+}
+```
+
+### Confirmation Dialog Example
+
+```go
+func (s *Service) DeleteItem(id string) error {
+ // Confirm before deleting
+ result, err := s.app.QuestionDialog().
+ SetTitle("Confirm Delete").
+ SetMessage("Are you sure you want to delete this item?").
+ SetButtons("Delete", "Cancel").
+ SetDefaultButton(1). // Default to Cancel
+ SetCancelButton(1).
+ Show()
+
+ if err != nil || result == "Cancel" {
+ return nil // User cancelled
+ }
+
+ // Perform deletion
+ return deleteFromDatabase(id)
+}
+```
+
+### Save Changes Dialog
+
+```go
+func (s *Editor) PromptSaveChanges() (bool, error) {
+ result, err := s.app.QuestionDialog().
+ SetTitle("Unsaved Changes").
+ SetMessage("Do you want to save your changes before closing?").
+ SetButtons("Save", "Don't Save", "Cancel").
+ SetDefaultButton(0).
+ SetCancelButton(2).
+ Show()
+
+ if err != nil {
+ return false, err
+ }
+
+ switch result {
+ case "Save":
+ return s.Save()
+ case "Don't Save":
+ return true, nil
+ case "Cancel":
+ return false, nil
+ }
+
+ return false, nil
+}
+```
+
+### Multi-File Processing
+
+```go
+func (s *Service) ProcessMultipleFiles() error {
+ // Select multiple files
+ paths, err := s.app.OpenFileDialog().
+ SetTitle("Select Files to Process").
+ SetFilters([]application.FileFilter{
+ {DisplayName: "Images", Pattern: "*.png;*.jpg"},
+ }).
+ PromptForMultipleSelection()
+
+ if err != nil {
+ return err
+ }
+
+ if len(paths) == 0 {
+ s.app.InfoDialog().
+ SetTitle("No Files Selected").
+ SetMessage("Please select at least one file.").
+ Show()
+ return nil
+ }
+
+ // Process files
+ for i, path := range paths {
+ err := processFile(path)
+ if err != nil {
+ s.app.ErrorDialog().
+ SetTitle("Processing Error").
+ SetMessage(fmt.Sprintf("Failed to process %s: %v", path, err)).
+ Show()
+ continue
+ }
+
+ // Show progress
+ s.app.EmitEvent("progress", map[string]interface{}{
+ "current": i + 1,
+ "total": len(paths),
+ })
+ }
+
+ // Show completion
+ s.app.InfoDialog().
+ SetTitle("Complete").
+ SetMessage(fmt.Sprintf("Successfully processed %d files", len(paths))).
+ Show()
+
+ return nil
+}
+```
+
+### Error Handling with Dialogs
+
+```go
+func (s *Service) SaveFile(data []byte) error {
+ // Select save location
+ path, err := s.app.SaveFileDialog().
+ SetTitle("Save File").
+ SetDefaultFilename("data.json").
+ SetFilters([]application.FileFilter{
+ {DisplayName: "JSON File", Pattern: "*.json"},
+ }).
+ PromptForSingleSelection()
+
+ if err != nil {
+ // User cancelled - not an error
+ return nil
+ }
+
+ // Attempt to save
+ err = os.WriteFile(path, data, 0644)
+ if err != nil {
+ // Show error dialog
+ s.app.ErrorDialog().
+ SetTitle("Save Failed").
+ SetMessage(fmt.Sprintf("Could not save file: %v", err)).
+ Show()
+ return err
+ }
+
+ // Show success
+ s.app.InfoDialog().
+ SetTitle("Success").
+ SetMessage("File saved successfully!").
+ Show()
+
+ return nil
+}
+```
+
+### Platform-Specific Defaults
+
+```go
+import (
+ "os"
+ "path/filepath"
+ "runtime"
+)
+
+func (s *Service) GetDefaultDirectory() string {
+ homeDir, _ := os.UserHomeDir()
+
+ switch runtime.GOOS {
+ case "windows":
+ return filepath.Join(homeDir, "Documents")
+ case "darwin":
+ return filepath.Join(homeDir, "Documents")
+ case "linux":
+ return filepath.Join(homeDir, "Documents")
+ default:
+ return homeDir
+ }
+}
+
+func (s *Service) OpenWithDefaults() (string, error) {
+ return s.app.OpenFileDialog().
+ SetTitle("Open File").
+ SetDefaultDirectory(s.GetDefaultDirectory()).
+ SetFilters([]application.FileFilter{
+ {DisplayName: "All Files", Pattern: "*.*"},
+ }).
+ PromptForSingleSelection()
+}
+```
+
+## Best Practices
+
+### ✅ Do
+
+- **Use native dialogs** - They match the platform's look and feel
+- **Provide clear titles** - Help users understand the purpose
+- **Set appropriate filters** - Guide users to correct file types
+- **Handle cancellation** - Check for errors (user may cancel)
+- **Show confirmation for destructive actions** - Use QuestionDialog
+- **Provide feedback** - Use InfoDialog for success messages
+- **Set sensible defaults** - Default directory, filename, etc.
+
+### ❌ Don't
+
+- **Don't ignore errors** - User cancellation returns an error
+- **Don't use ambiguous button labels** - "OK" vs "Save"/"Cancel"
+- **Don't overuse dialogs** - They interrupt workflow
+- **Don't show errors for cancellation** - It's a normal action
+- **Don't forget file filters** - Help users find the right files
+- **Don't hardcode paths** - Use os.UserHomeDir() or similar
+
+## Dialog Types by Platform
+
+### macOS
+
+- Dialogs slide down from title bar
+- "Sheet" style attached to parent window
+- Native macOS appearance
+
+### Windows
+
+- Standard Windows dialogs
+- Follows Windows design guidelines
+- Modern Windows 10/11 appearance
+
+### Linux
+
+- GTK dialogs on GTK-based systems
+- Qt dialogs on Qt-based systems
+- Matches desktop environment
+
+## Common Patterns
+
+### "Save As" Pattern
+
+```go
+func (s *Service) SaveAs(currentPath string) (string, error) {
+ // Extract filename from current path
+ filename := filepath.Base(currentPath)
+
+ // Show save dialog
+ path, err := s.app.SaveFileDialog().
+ SetTitle("Save As").
+ SetDefaultFilename(filename).
+ PromptForSingleSelection()
+
+ if err != nil {
+ return "", err
+ }
+
+ return path, nil
+}
+```
+
+### "Open Recent" Pattern
+
+```go
+func (s *Service) OpenRecent(recentPath string) error {
+ // Check if file still exists
+ if _, err := os.Stat(recentPath); os.IsNotExist(err) {
+ result, _ := s.app.QuestionDialog().
+ SetTitle("File Not Found").
+ SetMessage("The file no longer exists. Remove from recent files?").
+ SetButtons("Remove", "Cancel").
+ Show()
+
+ if result == "Remove" {
+ s.removeFromRecent(recentPath)
+ }
+
+ return err
+ }
+
+ return s.openFile(recentPath)
+}
+```
diff --git a/docs/src/content/docs/reference/events.mdx b/docs/src/content/docs/reference/events.mdx
new file mode 100644
index 000000000..a75ea62d5
--- /dev/null
+++ b/docs/src/content/docs/reference/events.mdx
@@ -0,0 +1,801 @@
+---
+title: Events API
+description: Complete reference for the Events API
+sidebar:
+ order: 4
+---
+
+import { Card, CardGrid } from "@astrojs/starlight/components";
+
+## Overview
+
+The Events API provides methods to emit and listen to events, enabling communication between different parts of your application.
+
+**Event Types:**
+- **Application Events** - App lifecycle events (startup, shutdown)
+- **Window Events** - Window state changes (focus, blur, resize)
+- **Custom Events** - User-defined events for app-specific communication
+
+**Communication Patterns:**
+- **Go to Frontend** - Emit events from Go, listen in JavaScript
+- **Frontend to Go** - Not directly (use service bindings instead)
+- **Frontend to Frontend** - Via Go or local runtime events
+- **Window to Window** - Target specific windows or broadcast to all
+
+## Event Methods (Go)
+
+### EmitEvent()
+
+Emits a custom event to all windows.
+
+```go
+func (a *App) EmitEvent(name string, data ...interface{})
+```
+
+**Parameters:**
+- `name` - Event name
+- `data` - Optional data to send with the event
+
+**Example:**
+```go
+// Emit simple event
+app.EmitEvent("user-logged-in")
+
+// Emit with data
+app.EmitEvent("data-updated", map[string]interface{}{
+ "count": 42,
+ "status": "success",
+})
+
+// Emit multiple values
+app.EmitEvent("progress", 75, "Processing files...")
+```
+
+### OnEvent()
+
+Listens for custom events in Go.
+
+```go
+func (a *App) OnEvent(name string, callback func(*CustomEvent)) func()
+```
+
+**Parameters:**
+- `name` - Event name to listen for
+- `callback` - Function called when event is emitted
+
+**Returns:** Cleanup function to remove the event listener
+
+**Example:**
+```go
+// Listen for events
+cleanup := app.OnEvent("user-action", func(e *application.CustomEvent) {
+ data := e.Data.(map[string]interface{})
+ action := data["action"].(string)
+ app.Logger.Info("User action", "action", action)
+})
+
+// Later, remove listener
+cleanup()
+```
+
+### Window-Specific Events
+
+Emit events to a specific window:
+
+```go
+// Emit to specific window
+window.EmitEvent("notification", "Hello from Go!")
+
+// Emit to all windows
+app.EmitEvent("global-update", data)
+```
+
+## Event Methods (Frontend)
+
+### On()
+
+Listens for events from Go.
+
+```javascript
+import { On } from '@wailsio/runtime'
+
+On(eventName, callback)
+```
+
+**Parameters:**
+- `eventName` - Name of the event to listen for
+- `callback` - Function called when event is received
+
+**Returns:** Cleanup function
+
+**Example:**
+```javascript
+import { On } from '@wailsio/runtime'
+
+// Listen for events
+const cleanup = On('data-updated', (data) => {
+ console.log('Count:', data.count)
+ console.log('Status:', data.status)
+ updateUI(data)
+})
+
+// Later, remove listener
+cleanup()
+```
+
+### Once()
+
+Listens for a single event occurrence.
+
+```javascript
+import { Once } from '@wailsio/runtime'
+
+Once(eventName, callback)
+```
+
+**Example:**
+```javascript
+import { Once } from '@wailsio/runtime'
+
+// Listen for first occurrence only
+Once('initialization-complete', (data) => {
+ console.log('App initialized!', data)
+ // This will only fire once
+})
+```
+
+### Off()
+
+Removes an event listener.
+
+```javascript
+import { Off } from '@wailsio/runtime'
+
+Off(eventName, callback)
+```
+
+**Example:**
+```javascript
+import { On, Off } from '@wailsio/runtime'
+
+const handler = (data) => {
+ console.log('Event received:', data)
+}
+
+// Start listening
+On('my-event', handler)
+
+// Stop listening
+Off('my-event', handler)
+```
+
+### OffAll()
+
+Removes all listeners for an event.
+
+```javascript
+import { OffAll } from '@wailsio/runtime'
+
+OffAll(eventName)
+```
+
+**Example:**
+```javascript
+// Remove all listeners for this event
+OffAll('data-updated')
+```
+
+## Application Events
+
+### OnApplicationEvent()
+
+Listens for application lifecycle events.
+
+```go
+func (a *App) OnApplicationEvent(eventType ApplicationEventType, callback func(*ApplicationEvent)) func()
+```
+
+**Event Types:**
+- `EventApplicationStarted` - Application has started
+- `EventApplicationShutdown` - Application is shutting down
+- `EventApplicationDebug` - Debug event (dev mode only)
+
+**Example:**
+```go
+// Handle application startup
+app.OnApplicationEvent(application.EventApplicationStarted, func(e *application.ApplicationEvent) {
+ app.Logger.Info("Application started")
+ // Initialize resources
+})
+
+// Handle application shutdown
+app.OnApplicationEvent(application.EventApplicationShutdown, func(e *application.ApplicationEvent) {
+ app.Logger.Info("Application shutting down")
+ // Cleanup resources, save state
+ database.Close()
+ saveSettings()
+})
+```
+
+## Window Events
+
+### OnWindowEvent()
+
+Listens for window-specific events.
+
+```go
+func (w *Window) OnWindowEvent(eventType WindowEventType, callback func(*WindowEvent)) func()
+```
+
+**Event Types:**
+- `EventWindowFocus` - Window gained focus
+- `EventWindowBlur` - Window lost focus
+- `EventWindowClose` - Window is closing
+- `EventWindowResize` - Window was resized
+- `EventWindowMove` - Window was moved
+
+**Example:**
+```go
+// Handle window focus
+window.OnWindowEvent(application.EventWindowFocus, func(e *application.WindowEvent) {
+ app.Logger.Info("Window focused")
+})
+
+// Handle window resize
+window.OnWindowEvent(application.EventWindowResize, func(e *application.WindowEvent) {
+ width, height := window.Size()
+ app.Logger.Info("Window resized", "width", width, "height", height)
+})
+```
+
+## Common Patterns
+
+These patterns demonstrate proven approaches for using events in real-world applications. Each pattern solves a specific communication challenge between your Go backend and frontend, helping you build responsive, well-structured applications.
+
+### Request/Response Pattern
+
+Use this when you want to notify the frontend about the completion of backend operations, such as after data fetching, file processing, or background tasks. The service binding returns data directly, while events provide additional notifications for UI updates like showing toast messages or refreshing lists.
+
+**Go:**
+
+```go
+// Service method
+type DataService struct {
+ app *application.Application
+}
+
+func (s *DataService) FetchData(query string) ([]Item, error) {
+ items := fetchFromDatabase(query)
+
+ // Emit event when done
+ s.app.EmitEvent("data-fetched", map[string]interface{}{
+ "query": query,
+ "count": len(items),
+ })
+
+ return items, nil
+}
+```
+
+**JavaScript:**
+
+```javascript
+import { FetchData } from './bindings/DataService'
+import { On } from '@wailsio/runtime'
+
+// Listen for completion event
+On('data-fetched', (data) => {
+ console.log(`Fetched ${data.count} items for query: ${data.query}`)
+ showNotification(`Found ${data.count} results`)
+})
+
+// Call service method
+const items = await FetchData("search term")
+displayItems(items)
+```
+
+### Progress Updates
+
+Ideal for long-running operations like file uploads, batch processing, large data imports, or video encoding. Emit progress events during the operation to update progress bars, status text, or step indicators in the UI, providing users with real-time feedback.
+
+**Go:**
+
+```go
+func (s *Service) ProcessFiles(files []string) error {
+ total := len(files)
+
+ for i, file := range files {
+ // Process file
+ processFile(file)
+
+ // Emit progress event
+ s.app.EmitEvent("progress", map[string]interface{}{
+ "current": i + 1,
+ "total": total,
+ "percent": float64(i+1) / float64(total) * 100,
+ "file": file,
+ })
+ }
+
+ s.app.EmitEvent("processing-complete")
+ return nil
+}
+```
+
+**JavaScript:**
+
+```javascript
+import { On, Once } from '@wailsio/runtime'
+
+// Update progress bar
+On('progress', (data) => {
+ progressBar.style.width = `${data.percent}%`
+ statusText.textContent = `Processing ${data.file}... (${data.current}/${data.total})`
+})
+
+// Handle completion
+Once('processing-complete', () => {
+ progressBar.style.width = '100%'
+ statusText.textContent = 'Complete!'
+ setTimeout(() => hideProgressBar(), 2000)
+})
+```
+
+### Multi-Window Communication
+
+Perfect for applications with multiple windows like settings panels, dashboards, or document viewers. Broadcast events to synchronize state across all windows (theme changes, user preferences) or send targeted events to specific windows for window-specific updates.
+
+**Go:**
+
+```go
+// Broadcast to all windows
+app.EmitEvent("theme-changed", "dark")
+
+// Send to specific window
+preferencesWindow.EmitEvent("settings-updated", settings)
+
+// Window-specific listener
+window1.OnEvent("request-data", func(e *application.CustomEvent) {
+ // Only this window will receive this event
+ window1.EmitEvent("data-response", data)
+})
+```
+
+**JavaScript:**
+
+```javascript
+import { On } from '@wailsio/runtime'
+
+// Listen in any window
+On('theme-changed', (theme) => {
+ document.body.className = theme
+})
+```
+
+### State Synchronization
+
+Use when you need to keep frontend and backend state in sync, such as user sessions, application configuration, or collaborative features. When state changes on the backend, emit events to update all connected frontends, ensuring consistency across your application.
+
+**Go:**
+
+```go
+type StateService struct {
+ app *application.Application
+ state map[string]interface{}
+ mu sync.RWMutex
+}
+
+func (s *StateService) UpdateState(key string, value interface{}) {
+ s.mu.Lock()
+ s.state[key] = value
+ s.mu.Unlock()
+
+ // Notify all windows
+ s.app.EmitEvent("state-updated", map[string]interface{}{
+ "key": key,
+ "value": value,
+ })
+}
+
+func (s *StateService) GetState(key string) interface{} {
+ s.mu.RLock()
+ defer s.mu.RUnlock()
+ return s.state[key]
+}
+```
+
+**JavaScript:**
+
+```javascript
+import { On } from '@wailsio/runtime'
+import { GetState } from './bindings/StateService'
+
+// Keep local state in sync
+let localState = {}
+
+On('state-updated', async (data) => {
+ localState[data.key] = data.value
+ updateUI(data.key, data.value)
+})
+
+// Initialize state
+const initialState = await GetState("all")
+localState = initialState
+```
+
+### Event-Driven Notifications
+
+Best for displaying user feedback like success confirmations, error alerts, or info messages. Instead of calling UI code directly from services, emit notification events that the frontend handles consistently, making it easy to change notification styles or add features like notification history.
+
+**Go:**
+
+```go
+type NotificationService struct {
+ app *application.Application
+}
+
+func (s *NotificationService) Success(message string) {
+ s.app.EmitEvent("notification", map[string]interface{}{
+ "type": "success",
+ "message": message,
+ })
+}
+
+func (s *NotificationService) Error(message string) {
+ s.app.EmitEvent("notification", map[string]interface{}{
+ "type": "error",
+ "message": message,
+ })
+}
+
+func (s *NotificationService) Info(message string) {
+ s.app.EmitEvent("notification", map[string]interface{}{
+ "type": "info",
+ "message": message,
+ })
+}
+```
+
+**JavaScript:**
+
+```javascript
+import { On } from '@wailsio/runtime'
+
+// Unified notification handler
+On('notification', (data) => {
+ const toast = document.createElement('div')
+ toast.className = `toast toast-${data.type}`
+ toast.textContent = data.message
+
+ document.body.appendChild(toast)
+
+ setTimeout(() => {
+ toast.classList.add('fade-out')
+ setTimeout(() => toast.remove(), 300)
+ }, 3000)
+})
+```
+
+## Complete Example
+
+**Go:**
+
+```go
+package main
+
+import (
+ "sync"
+ "time"
+ "github.com/wailsapp/wails/v3/pkg/application"
+)
+
+type EventDemoService struct {
+ app *application.Application
+ mu sync.Mutex
+}
+
+func NewEventDemoService(app *application.Application) *EventDemoService {
+ service := &EventDemoService{app: app}
+
+ // Listen for custom events
+ app.OnEvent("user-action", func(e *application.CustomEvent) {
+ data := e.Data.(map[string]interface{})
+ app.Logger.Info("User action received", "data", data)
+ })
+
+ return service
+}
+
+func (s *EventDemoService) StartLongTask() {
+ go func() {
+ s.app.EmitEvent("task-started")
+
+ for i := 1; i <= 10; i++ {
+ time.Sleep(500 * time.Millisecond)
+
+ s.app.EmitEvent("task-progress", map[string]interface{}{
+ "step": i,
+ "total": 10,
+ "percent": i * 10,
+ })
+ }
+
+ s.app.EmitEvent("task-completed", map[string]interface{}{
+ "message": "Task finished successfully!",
+ })
+ }()
+}
+
+func (s *EventDemoService) BroadcastMessage(message string) {
+ s.app.EmitEvent("broadcast", message)
+}
+
+func main() {
+ app := application.New(application.Options{
+ Name: "Event Demo",
+ })
+
+ // Handle application lifecycle
+ app.OnApplicationEvent(application.EventApplicationStarted, func(e *application.ApplicationEvent) {
+ app.Logger.Info("Application started!")
+ })
+
+ app.OnApplicationEvent(application.EventApplicationShutdown, func(e *application.ApplicationEvent) {
+ app.Logger.Info("Application shutting down...")
+ })
+
+ // Register service
+ service := NewEventDemoService(app)
+ app.RegisterService(application.NewService(service))
+
+ // Create window
+ window := app.NewWebviewWindow()
+
+ // Handle window events
+ window.OnWindowEvent(events.Common.WindowFocus, func(e *application.WindowEvent) {
+ window.EmitEvent("window-state", "focused")
+ })
+
+ window.OnWindowEvent(events.Common.WindowLostFocus, func(e *application.WindowEvent) {
+ window.EmitEvent("window-state", "blurred")
+ })
+
+ window.Show()
+ app.Run()
+}
+```
+
+**JavaScript:**
+
+```javascript
+import { On, Once } from '@wailsio/runtime'
+import { StartLongTask, BroadcastMessage } from './bindings/EventDemoService'
+
+// Task events
+On('task-started', () => {
+ console.log('Task started...')
+ document.getElementById('status').textContent = 'Running...'
+})
+
+On('task-progress', (data) => {
+ const progressBar = document.getElementById('progress')
+ progressBar.style.width = `${data.percent}%`
+ console.log(`Step ${data.step} of ${data.total}`)
+})
+
+Once('task-completed', (data) => {
+ console.log('Task completed!', data.message)
+ document.getElementById('status').textContent = data.message
+})
+
+// Broadcast events
+On('broadcast', (message) => {
+ console.log('Broadcast:', message)
+ alert(message)
+})
+
+// Window state events
+On('window-state', (state) => {
+ console.log('Window is now:', state)
+ document.body.dataset.windowState = state
+})
+
+// Trigger long task
+document.getElementById('startTask').addEventListener('click', async () => {
+ await StartLongTask()
+})
+
+// Send broadcast
+document.getElementById('broadcast').addEventListener('click', async () => {
+ const message = document.getElementById('message').value
+ await BroadcastMessage(message)
+})
+```
+
+## Built-in Events
+
+Wails provides built-in system events for application and window lifecycle. These events are emitted automatically by the framework.
+
+### Common Events vs Platform-Native Events
+
+Wails provides two types of system events:
+
+**Common Events** (`events.Common.*`) are cross-platform abstractions that work consistently across macOS, Windows, and Linux. These are the events you should use in your application for maximum portability.
+
+**Platform-Native Events** (`events.Mac.*`, `events.Windows.*`, `events.Linux.*`) are the underlying OS-specific events that Common Events are mapped from. These provide access to platform-specific behaviors and edge cases.
+
+**How They Work:**
+
+```go
+import "github.com/wailsapp/wails/v3/pkg/events"
+
+// ✅ RECOMMENDED: Use Common Events for cross-platform code
+window.OnWindowEvent(events.Common.WindowClosing, func(e *application.WindowEvent) {
+ // This works on all platforms
+})
+
+// Platform-specific events for advanced use cases
+window.OnWindowEvent(events.Mac.WindowWillClose, func(e *application.WindowEvent) {
+ // macOS-specific "will close" event (before WindowClosing)
+})
+
+window.OnWindowEvent(events.Windows.WindowClosing, func(e *application.WindowEvent) {
+ // Windows-specific close event
+})
+```
+
+**Event Mapping:**
+
+Platform-native events are automatically mapped to Common Events:
+
+- macOS: `events.Mac.WindowShouldClose` → `events.Common.WindowClosing`
+- Windows: `events.Windows.WindowClosing` → `events.Common.WindowClosing`
+- Linux: `events.Linux.WindowDeleteEvent` → `events.Common.WindowClosing`
+
+This mapping happens automatically in the background, so when you listen for `events.Common.WindowClosing`, you'll receive it regardless of the platform.
+
+**When to Use Each:**
+
+- **Use Common Events** for 99% of your application code - they provide consistent behavior across platforms
+- **Use Platform-Native Events** only when you need platform-specific functionality that isn't available in Common Events (e.g., macOS-specific window lifecycle events, Windows power management events)
+
+### Application Events
+
+| Event | Description | When Emitted | Cancellable |
+|-------|-------------|--------------|-------------|
+| `ApplicationOpenedWithFile` | Application opened with a file | When app is launched with a file (e.g., from file association) | No |
+| `ApplicationStarted` | Application has finished launching | After app initialization is complete and app is ready | No |
+| `ApplicationLaunchedWithUrl` | Application launched with a URL | When app is launched via URL scheme | No |
+| `ThemeChanged` | System theme changed | When OS theme switches between light/dark mode | No |
+
+**Usage:**
+
+```go
+import "github.com/wailsapp/wails/v3/pkg/events"
+
+app.OnApplicationEvent(events.Common.ApplicationStarted, func(e *application.ApplicationEvent) {
+ app.Logger.Info("Application ready!")
+})
+
+app.OnApplicationEvent(events.Common.ThemeChanged, func(e *application.ApplicationEvent) {
+ // Update app theme
+})
+```
+
+### Window Events
+
+| Event | Description | When Emitted | Cancellable |
+|-------|-------------|--------------|-------------|
+| `WindowClosing` | Window is about to close | Before window closes (user clicked X, Close() called) | Yes |
+| `WindowDidMove` | Window moved to new position | After window position changes (debounced) | No |
+| `WindowDidResize` | Window was resized | After window size changes | No |
+| `WindowDPIChanged` | Window DPI scaling changed | When moving between monitors with different DPI (Windows) | No |
+| `WindowFilesDropped` | Files dropped via native OS drag-drop | After files are dropped from OS onto window | No |
+| `WindowFocus` | Window gained focus | When window becomes active | No |
+| `WindowFullscreen` | Window entered fullscreen | After Fullscreen() or user enters fullscreen | No |
+| `WindowHide` | Window was hidden | After Hide() or window becomes occluded | No |
+| `WindowLostFocus` | Window lost focus | When window becomes inactive | No |
+| `WindowMaximise` | Window was maximized | After Maximise() or user maximizes | Yes (macOS) |
+| `WindowMinimise` | Window was minimized | After Minimise() or user minimizes | Yes (macOS) |
+| `WindowRestore` | Window restored from min/max state | After Restore() (Windows primarily) | No |
+| `WindowRuntimeReady` | Wails runtime loaded and ready | When JavaScript runtime initialization completes | No |
+| `WindowShow` | Window became visible | After Show() or window becomes visible | No |
+| `WindowUnFullscreen` | Window exited fullscreen | After UnFullscreen() or user exits fullscreen | No |
+| `WindowUnMaximise` | Window exited maximized state | After UnMaximise() or user unmaximizes | Yes (macOS) |
+| `WindowUnMinimise` | Window exited minimized state | After UnMinimise()/Restore() or user restores | Yes (macOS) |
+| `WindowZoomIn` | Window content zoom increased | After ZoomIn() called (macOS primarily) | Yes (macOS) |
+| `WindowZoomOut` | Window content zoom decreased | After ZoomOut() called (macOS primarily) | Yes (macOS) |
+| `WindowZoomReset` | Window content zoom reset to 100% | After ZoomReset() called (macOS primarily) | Yes (macOS) |
+| `WindowDropZoneFilesDropped` | Files dropped on JS-defined drop zone | When files dropped onto element with drop zone | No |
+
+**Usage:**
+
+```go
+import "github.com/wailsapp/wails/v3/pkg/events"
+
+// Listen for window events
+window.OnWindowEvent(events.Common.WindowFocus, func(e *application.WindowEvent) {
+ app.Logger.Info("Window focused")
+})
+
+// Cancel window close
+window.RegisterHook(events.Common.WindowClosing, func(e *application.WindowEvent) {
+ result, _ := app.QuestionDialog().
+ SetMessage("Close window?").
+ SetButtons("Yes", "No").
+ Show()
+
+ if result == "No" {
+ e.Cancel() // Prevent close
+ }
+})
+
+// Wait for runtime ready
+window.OnWindowEvent(events.Common.WindowRuntimeReady, func(e *application.WindowEvent) {
+ app.Logger.Info("Runtime ready, safe to emit events to frontend")
+ window.EmitEvent("app-initialized", data)
+})
+```
+
+**Important Notes:**
+
+- **WindowRuntimeReady** is critical - wait for this event before emitting events to the frontend
+- **WindowDidMove** and **WindowDidResize** are debounced (50ms default) to prevent event flooding
+- **Cancellable events** can be prevented by calling `event.Cancel()` in a `RegisterHook()` handler
+- **WindowFilesDropped** is for native OS file drops; **WindowDropZoneFilesDropped** is for web-based drop zones
+- Some events are platform-specific (e.g., WindowDPIChanged on Windows, zoom events primarily on macOS)
+
+## Event Naming Conventions
+
+```go
+// Good - descriptive and specific
+app.EmitEvent("user:logged-in", user)
+app.EmitEvent("data:fetch:complete", results)
+app.EmitEvent("ui:theme:changed", theme)
+
+// Bad - vague and unclear
+app.EmitEvent("event1", data)
+app.EmitEvent("update", stuff)
+app.EmitEvent("e", value)
+```
+
+## Performance Considerations
+
+### Debouncing High-Frequency Events
+
+```go
+type Service struct {
+ app *application.Application
+ lastEmit time.Time
+ debounceWindow time.Duration
+}
+
+func (s *Service) EmitWithDebounce(event string, data interface{}) {
+ now := time.Now()
+ if now.Sub(s.lastEmit) < s.debounceWindow {
+ return // Skip this emission
+ }
+
+ s.app.EmitEvent(event, data)
+ s.lastEmit = now
+}
+```
+
+### Throttling Events
+
+```javascript
+import { On } from '@wailsio/runtime'
+
+let lastUpdate = 0
+const throttleMs = 100
+
+On('high-frequency-event', (data) => {
+ const now = Date.now()
+ if (now - lastUpdate < throttleMs) {
+ return // Skip this update
+ }
+
+ processUpdate(data)
+ lastUpdate = now
+})
+```
diff --git a/docs/src/content/docs/reference/frontend-runtime.mdx b/docs/src/content/docs/reference/frontend-runtime.mdx
new file mode 100644
index 000000000..84ab7a7aa
--- /dev/null
+++ b/docs/src/content/docs/reference/frontend-runtime.mdx
@@ -0,0 +1,809 @@
+---
+title: Frontend Runtime
+description: The Wails JavaScript runtime package for frontend integration
+sidebar:
+ order: 1
+---
+
+The Wails frontend runtime is the standard library for Wails applications. It provides a
+number of features that may be used in your applications, including:
+
+- Window management
+- Dialogs
+- Browser integration
+- Clipboard
+- Menus
+- System information
+- Events
+- Context Menus
+- Screens
+- WML (Wails Markup Language)
+
+The runtime is required for integration between Go and the frontend. There are 2
+ways to integrate the runtime:
+
+- Using the `@wailsio/runtime` package
+- Using a pre-built bundle
+
+## Using the npm package
+
+The `@wailsio/runtime` package is a JavaScript package that provides access to
+the Wails runtime from the frontend. It is used by all standard templates
+and is the recommended way to integrate the runtime into your application.
+By using the `@wailsio/runtime` package, you will only include the parts of the runtime that you use.
+
+The package is available on npm and can be installed using:
+
+```shell
+npm install --save @wailsio/runtime
+```
+
+## Using a pre-built bundle
+
+Some projects will not use a Javascript bundler and may prefer to use a
+pre-built bundled version of the runtime. This version can be generated locally
+using the following command:
+
+```shell
+wails3 generate runtime
+```
+
+The command will output a `runtime.js` (and `runtime.debug.js`) file in the current
+directory. This file is an ES module that can be imported by your application scripts
+just like the npm package, but the API is also exported to the global window object,
+so for simpler applications you can use it as follows:
+
+```html
+
+
+
+
+
+
+
+```
+
+:::caution
+It is important to include the `type="module"` attribute on the `
-
-
-
-