@tauri-apps/api

Active contributors: Lucas Fernandes Nogueira, Amr Bashir, Tony

Purpose

packages/api is the TypeScript library that JavaScript frontends import to talk to the Tauri Rust backend. It exposes one ESM entry point with twelve sub-modules, each mirroring a slice of the Rust API: app metadata, command invocation (core), DPI helpers, the event bus, image and path utilities, menus, mocks for unit testing, the system tray, and webview/window control.

It is published to npm as @tauri-apps/api. The bindings work both as ESM imports with a bundler and via the global window.__TAURI__ object when app.withGlobalTauri = true in tauri.conf.json.

Directory layout

packages/api/
├── package.json            # public exports map
├── rollup.config.ts        # emits dual ESM/CJS to packages/api/dist/
├── eslint.config.js
├── tsconfig.json
└── src/
    ├── index.ts            # re-exports every sub-module as a namespace
    ├── app.ts              # window-less app metadata: name, version, identifier
    ├── core.ts             # invoke<T>(), Channel, Resource, isPermissionGranted, …
    ├── dpi.ts              # PhysicalSize / LogicalSize / PhysicalPosition / LogicalPosition / Rect
    ├── event.ts            # listen, emit, once, channels
    ├── global.d.ts         # ambient declarations for window.__TAURI_INTERNALS__
    ├── image.ts            # Image (binary) helpers
    ├── menu.ts / menu/     # MenuItem, CheckMenuItem, Submenu, IconMenuItem, PredefinedMenuItem
    ├── mocks.ts            # mockIPC, mockWindows, mockConvertFileSrc — used in vitest tests
    ├── path.ts             # 21 KB: appCacheDir, pictureDir, BaseDirectory enum, join, …
    ├── tray.ts             # TrayIcon, TrayIconBuilder
    ├── webview.ts / webviewWindow.ts
    └── window.ts           # 76,764 bytes: Window class, getCurrent(), getAll(), event helpers

Key abstractions

Symbol	File	Role
invoke<T>(name, args?)	packages/api/src/core.ts	Single typed bridge to a Rust #[command].
Channel<T>	packages/api/src/core.ts	Subscribe to a long-lived stream produced by tauri::ipc::Channel.
Resource	packages/api/src/core.ts	Wrapper around a ResourceId with close() semantics.
Window / getCurrent / getAll	packages/api/src/window.ts	The Window class and global accessors.
Webview / WebviewWindow	packages/api/src/webview.ts, webviewWindow.ts	Per-webview controls.
Menu / Submenu / MenuItem …	packages/api/src/menu/	Mirror of the Rust menu types.
TrayIcon, TrayIconBuilder	packages/api/src/tray.ts	Mirror of crates/tauri/src/tray/.
BaseDirectory / join / appCacheDir etc.	packages/api/src/path.ts	Cross-platform path helpers backed by Rust commands.
mockIPC, mockWindows	packages/api/src/mocks.ts	Vitest helpers: stub invoke and the window registry.

How it works

Every public function ultimately calls core.invoke (defined in packages/api/src/core.ts), which posts to window.__TAURI_INTERNALS__.postMessage. WRY's IPC bridge picks the message up and delivers it to Tauri's AppManager.

sequenceDiagram
    participant App as JS app
    participant API as @tauri-apps/api
    participant Bridge as window.__TAURI_INTERNALS__
    participant Rust as tauri::AppManager

    App->>API: window.getCurrent().setTitle("Hi")
    API->>API: serialize args
    API->>Bridge: postMessage({cmd: "plugin:window|set_title", ...})
    Bridge->>Rust: IPC handler
    Rust-->>Bridge: response payload
    Bridge-->>API: resolve promise
    API-->>App: void

The core.ts module also implements:

• Channel<T>: a pull-style listener that is bound to an internal __TAURI_CHANNEL__ callback. Used for streaming responses (e.g. download progress).
• Resource: holds a rid returned by Rust and calls plugin:resources|close on close().
• Permissions / capabilities helpers (addPluginListener, convertFileSrc).

Build

rollup.config.ts emits index.js (ESM), index.cjs (CJS), and matching .d.ts files for every sub-module. The exports map in package.json exposes the same modules under both import and require conditions.

Type-checking runs tsc --noEmit (CI: lint-js.yml). Tests live as *.test.ts next to source and run via pnpm --filter @tauri-apps/api test (vitest).

Integration points

• Up: consumed by every Tauri app's frontend. The example app at examples/api exercises every module.
• Down: posts to window.__TAURI_INTERNALS__ which is wired up by crates/tauri-runtime-wry's WRY IPC handler. The Rust side dispatches through crates/tauri/src/ipc/ and crates/tauri/src/manager/.

Entry points for modification

Goal	Start here
Add a new top-level module	packages/api/src/<name>.ts, register in index.ts and package.json#exports
Add a method on Window	packages/api/src/window.ts plus the matching Rust command in crates/tauri/src/window/
Tweak invoke behaviour	packages/api/src/core.ts
Improve mock helpers	packages/api/src/mocks.ts
Update bindings after a Rust API change	The matching file under packages/api/src/

See systems/ipc-and-commands for the wire format and crates/tauri for the Rust side.