0
# Tauri API
1
2
The Tauri API provides comprehensive TypeScript/JavaScript bindings for building cross-platform desktop applications with web technologies. It enables frontend frameworks to communicate with Rust-based backend functionality through a complete message-passing interface, offering desktop-specific APIs for window management, system integration, file access, and native platform features.
3
4
## Package Information
5
6
- **Package Name**: @tauri-apps/api
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install @tauri-apps/api`
10
11
## Core Imports
12
13
```typescript
14
import { app, window, event, core, path, menu, tray, image, dpi } from '@tauri-apps/api';
15
```
16
17
Individual module imports:
18
19
```typescript
20
import { getCurrentWindow } from '@tauri-apps/api/window';
21
import { listen } from '@tauri-apps/api/event';
22
import { invoke } from '@tauri-apps/api/core';
23
import { getVersion, getName } from '@tauri-apps/api/app';
24
import { Menu, MenuItem } from '@tauri-apps/api/menu';
25
import { TrayIcon } from '@tauri-apps/api/tray';
26
```
27
28
CommonJS (if needed):
29
30
```javascript
31
const { app, window, event, core, menu, tray } = require('@tauri-apps/api');
32
```
33
34
## Basic Usage
35
36
```typescript
37
import { getCurrentWindow } from '@tauri-apps/api/window';
38
import { listen } from '@tauri-apps/api/event';
39
import { invoke } from '@tauri-apps/api/core';
40
41
// Get current window and modify it
42
const currentWindow = getCurrentWindow();
43
await currentWindow.setTitle('My Tauri App');
44
await currentWindow.setSize({ width: 800, height: 600 });
45
46
// Listen for window events
47
await listen('window-close-requested', (event) => {
48
console.log('Window close requested');
49
});
50
51
// Invoke Rust backend commands
52
const result = await invoke('my_custom_command', {
53
message: 'Hello from frontend'
54
});
55
```
56
57
## Architecture
58
59
The Tauri API is organized into focused modules that provide different aspects of desktop functionality:
60
61
- **Core IPC System**: Foundation for communicating with Rust backend (`core`)
62
- **Window Management**: Control over application windows and webviews (`window`, `webview`, `webviewWindow`)
63
- **System Integration**: Native desktop features like menus, tray icons, and app lifecycle (`app`, `menu`, `tray`)
64
- **Event System**: Real-time communication between frontend and backend (`event`)
65
- **Utilities**: Cross-platform helpers for paths, images, and device pixels (`path`, `image`, `dpi`)
66
- **Testing**: Mock implementations for development and testing (`mocks`)
67
68
## Capabilities
69
70
### Core IPC Communication
71
72
Foundation for all backend communication, including command invocation, plugin system, and resource management.
73
74
```typescript { .api }
75
function invoke<T>(cmd: string, args?: InvokeArgs, options?: InvokeOptions): Promise<T>;
76
function isTauri(): boolean;
77
function convertFileSrc(filePath: string, protocol?: string): string;
78
79
class Channel<T> {
80
constructor(onmessage?: (response: T) => void);
81
readonly id: number;
82
onmessage: (response: T) => void;
83
}
84
85
type InvokeArgs = Record<string, unknown> | number[] | ArrayBuffer | Uint8Array;
86
interface InvokeOptions {
87
headers: HeadersInit;
88
}
89
```
90
91
[Core IPC & Plugins](./core-ipc.md)
92
93
### Application Lifecycle & Metadata
94
95
Control application behavior, retrieve metadata, and manage lifecycle events including visibility, theming, and platform-specific features.
96
97
```typescript { .api }
98
// Application metadata
99
function getVersion(): Promise<string>;
100
function getName(): Promise<string>;
101
function getTauriVersion(): Promise<string>;
102
function getIdentifier(): Promise<string>;
103
function getBundleType(): Promise<BundleType>;
104
105
// Application visibility and state
106
function show(): Promise<void>;
107
function hide(): Promise<void>;
108
function setTheme(theme?: Theme | null): Promise<void>;
109
function setDockVisibility(visible: boolean): Promise<void>;
110
111
// Application icon and data
112
function defaultWindowIcon(): Promise<Image | null>;
113
function fetchDataStoreIdentifiers(): Promise<DataStoreIdentifier[]>;
114
function removeDataStore(identifier: DataStoreIdentifier): Promise<void>;
115
116
enum BundleType {
117
Nsis = 'nsis',
118
Msi = 'msi',
119
Deb = 'deb',
120
Rpm = 'rpm',
121
AppImage = 'appimage',
122
App = 'app'
123
}
124
```
125
126
[Application Lifecycle](./app-lifecycle.md)
127
128
### Window & Webview Management
129
130
Complete control over application windows, webviews, and their properties including size, position, decorations, and advanced features.
131
132
```typescript { .api }
133
class Window {
134
static getCurrent(): Window;
135
static getAll(): Promise<Window[]>;
136
setTitle(title: string): Promise<void>;
137
setSize(size: LogicalSize | PhysicalSize): Promise<void>;
138
setPosition(position: LogicalPosition | PhysicalPosition): Promise<void>;
139
show(): Promise<void>;
140
hide(): Promise<void>;
141
close(): Promise<void>;
142
}
143
144
class WebviewWindow {
145
constructor(label: string, options?: WebviewWindowOptions);
146
setBackgroundColor(color: Color): Promise<void>;
147
}
148
149
function getCurrentWindow(): Window;
150
function getCurrentWebviewWindow(): WebviewWindow;
151
```
152
153
[Window & Webview Management](./window-management.md)
154
155
### System Integration
156
157
Native desktop features including system tray icons and platform-specific functionality.
158
159
```typescript { .api }
160
// System tray management
161
class TrayIcon {
162
static new(options: TrayIconOptions): Promise<TrayIcon>;
163
setIcon(icon: Image | string): Promise<void>;
164
setMenu(menu: Menu): Promise<void>;
165
setTooltip(tooltip: string): Promise<void>;
166
setVisible(visible: boolean): Promise<void>;
167
setTitle(title?: string): Promise<void>;
168
}
169
170
interface TrayIconOptions {
171
id?: string;
172
icon?: Image | string;
173
tooltip?: string;
174
title?: string;
175
menu?: Menu;
176
}
177
```
178
179
[System Integration](./system-integration.md)
180
181
### Menu System
182
183
Comprehensive native menu functionality including menu bars, context menus, and system tray menus with support for different item types.
184
185
```typescript { .api }
186
// Main menu classes
187
class Menu {
188
static new(opts?: MenuOptions): Promise<Menu>;
189
static default(): Promise<Menu>;
190
append<T extends MenuItemType>(items: T | T[]): Promise<void>;
191
popup(at?: Position, window?: Window): Promise<void>;
192
setAsAppMenu(): Promise<Menu | null>;
193
items(): Promise<MenuItemInstance[]>;
194
}
195
196
class MenuItem {
197
static new(opts: MenuItemOptions): Promise<MenuItem>;
198
setText(text: string): Promise<void>;
199
setEnabled(enabled: boolean): Promise<void>;
200
}
201
202
class Submenu {
203
static new(opts: SubmenuOptions): Promise<Submenu>;
204
append<T extends MenuItemType>(items: T | T[]): Promise<void>;
205
}
206
207
// Menu item types
208
interface MenuItemOptions {
209
text: string;
210
accelerator?: string;
211
action?: () => void;
212
}
213
214
interface SubmenuOptions {
215
text: string;
216
items?: MenuItemType[];
217
}
218
```
219
220
[Menu System](./menu-system.md)
221
222
### Event System
223
224
Real-time bidirectional communication between frontend and backend with support for custom events and built-in system events.
225
226
```typescript { .api }
227
function listen<T>(event: EventName, handler: EventCallback<T>, options?: Options): Promise<UnlistenFn>;
228
function once<T>(event: EventName, handler: EventCallback<T>, options?: Options): Promise<UnlistenFn>;
229
function emit<T>(event: string, payload?: T): Promise<void>;
230
function emitTo<T>(target: EventTarget, event: string, payload?: T): Promise<void>;
231
232
type EventCallback<T> = (event: Event<T>) => void;
233
type UnlistenFn = () => void;
234
235
interface Event<T> {
236
event: string;
237
id: number;
238
payload: T;
239
}
240
```
241
242
[Event System](./events.md)
243
244
### Utilities
245
246
Cross-platform utilities for path handling, image processing, device pixel calculations, and platform abstraction.
247
248
```typescript { .api }
249
// Path utilities
250
function join(...paths: string[]): Promise<string>;
251
function resolve(...paths: string[]): Promise<string>;
252
function appDataDir(): Promise<string>;
253
function homeDir(): Promise<string>;
254
255
// Image handling
256
class Image {
257
static fromPath(path: string): Promise<Image>;
258
static fromBytes(bytes: Uint8Array): Promise<Image>;
259
size(): Promise<ImageSize>;
260
rgba(): Promise<Uint8Array>;
261
}
262
263
// DPI handling
264
class LogicalSize {
265
constructor(width: number, height: number);
266
toPhysical(scaleFactor: number): PhysicalSize;
267
}
268
```
269
270
[Utilities](./utilities.md)
271
272
### Testing Support
273
274
Mock implementations for testing Tauri applications without requiring the full Tauri runtime environment.
275
276
```typescript { .api }
277
function mockIPC(cb: (cmd: string, payload?: InvokeArgs) => unknown, options?: MockIPCOptions): void;
278
function mockWindows(current: string, ...additionalWindows: string[]): void;
279
function clearMocks(): void;
280
281
interface MockIPCOptions {
282
shouldMockEvents?: boolean;
283
}
284
```
285
286
[Testing & Mocks](./testing.md)
287
288
## Error Handling
289
290
Most Tauri API functions return Promises that may reject with errors. Common error scenarios include:
291
292
- **Permission denied**: Operations requiring elevated permissions
293
- **Invalid parameters**: Malformed arguments or invalid values
294
- **Platform limitations**: Features not available on current platform
295
- **IPC failures**: Communication errors with Rust backend
296
297
```typescript
298
try {
299
await getCurrentWindow().setTitle('New Title');
300
} catch (error) {
301
console.error('Failed to set window title:', error);
302
}
303
```
304
305
## Platform Support
306
307
The Tauri API supports Windows, macOS, and Linux with platform-specific features clearly documented. Some functionality (like dock visibility) is only available on specific platforms and will be no-ops on unsupported systems.