Tauri SDK overview
The Tauri SDK adds IM to desktop apps built with Tauri 2 on Windows, macOS and Linux. It has two parts, an npm package and a Rust plugin. The JavaScript part is the Web SDK core, so every module's API, the subscribable lists and the events are exactly the same as in the Web SDK. The Rust plugin provides the local database, the system keychain, a connection that stays up after windows are closed, system notifications, badges and the taskbar, and sending and receiving files by local path.
// 引擎页（不显示的页面）：长连接、同步和提醒都在这里，整个应用一个
import { createDRTauriEngine } from '@deeprespond/im-tauri/engine';
createDRTauriEngine({ appKey: '1575529652#demo', apiUrl: 'https://im.example.com' });// 界面窗口：只需要 AppKey，之后的用法与 Web SDK 相同
import { createDRTauriClient } from '@deeprespond/im-tauri';
const im = createDRTauriClient({ appKey: '1575529652#demo' });
if (!im.auth.currentUser) await im.auth.loginWithTicket({ ticket }); // 已登录过的，启动后自动恢复
const list = im.conversations.list(); // 会话列表：先显示本地数据，后台同步
list.subscribe(() => render(list.getSnapshot().items));
| Item | Details |
|---|---|
| Current version | 1.1.1 (Versions and support) |
| Install | npm: @deeprespond/im-tauri; Rust: tauri-plugin-deeprespond-im, on exactly the same version |
| Systems | Windows 10 (1809), macOS 12, Linux (WebKitGTK 4.1) and later desktops |
| Requirements | Tauri 2.12 and Rust 1.90 or later |
| Not supported | Tauri on mobile; audio and video calls on Linux |
What you can build
The client object im in a UI window is the same as the Web SDK client, plus a desktop-specific im.desktop. For each module, read the Web SDK docs:
| Property | Purpose | Docs |
|---|---|---|
im.auth, im.connection, im.config | Sign-in, sign-out and password changes; connection state and diagnostics; the app's runtime configuration | Initialization, sign-in and connection |
im.conversations | Conversation list, unread counts, pinning, drafts, typing indicators | Conversations |
im.messages | Message lists, sending, recalling, reactions, pinning, read receipts, local search | Messages |
im.users, im.friends, im.presence, im.devices | Your own and other users' profiles, friends and block list, presence, your signed-in devices | Users, friends and presence |
im.groups | Groups, members, join requests and invitations, invite links | Groups |
im.files | Uploads, downloads, group files, voice recording | Files |
im.chatrooms | Chat rooms | Chat rooms |
im.calls | One-to-one and group voice and video calls | Audio and video calls |
im.channels | Standalone RTC channels: join, resume, media, state and leave | Channels |
im.push, im.reports | Push settings, muting conversations; reports | Alerts, push settings and reports |
im.on(), DRError | Events, errors and message text | Events and errors |
im.desktop | System notifications, badges and the taskbar, picking and dropping files, local previews, downloading and opening files, diagnostics | Desktop features |
Three more pages in this section are specific to Tauri: start with the Quickstart; the engine page, multiple windows, quitting and tray apps are in Engine and windows; notifications, badges, file paths and so on are in Desktop features.
Packages
| Package | Contents |
|---|---|
npm @deeprespond/im-tauri | createDRTauriClient for UI windows, onFilesDropped for dropped files, the desktop module types and the DesktopEvents event types. It also re-exports everything from @deeprespond/im-web (DRError, module types and so on), so you don't import from the Web SDK separately |
npm @deeprespond/im-tauri/engine | createDRTauriEngine for the engine page |
crate tauri-plugin-deeprespond-im | The Rust plugin, registered in src-tauri; see the Quickstart |
- Dependencies: the npm package has
@deeprespond/im-web(same version) and@tauri-apps/api(2.12 or later) as peer dependencies; install them too. - React and Vue: use the Web SDK bindings
@deeprespond/im-web-reactand@deeprespond/im-web-vuedirectly, passing the result ofcreateDRTauriClient()toDRProvider(or the Vue plugin). See Using React and Vue. - Display helpers and message text: import from
@deeprespond/im-web/renderand@deeprespond/im-web/locale/zh-CN, as in the Web SDK.
Plugin features
| Feature | Default | Details |
|---|---|---|
tray | On | The tray icon blinking helper desktop.trayBlink(); enables Tauri's tray-icon feature. Apps without a tray can turn off default features |
sqlcipher | Off | Encrypts the local database, see Encrypting the local database. Links SQLCipher, which makes the installer larger |
heic | Off | On Linux, uses the system libheif (1.17 or later) to convert HEIC photos to images before sending, see Sending local files |
Versions
The npm package and the Rust plugin are released together with the same version number, and both sides must use the same version. The engine compares them on startup and refuses to create the client with unsupported (details.reason is version_mismatch) if they differ. Pin exact versions in both package.json and Cargo.toml, and change them together when you upgrade.
Requirements
| System | Minimum version | WebView | System notifications | Badges | Audio and video calls |
|---|---|---|---|---|---|
| Windows | 10 (1809), 11; x64, Arm64 | WebView2 (Chromium 100 or later) | Windows notifications | Number overlay on the taskbar button, taskbar flashing | Supported |
| macOS | 12; Intel and Apple silicon | The system WKWebView, with Safari updated to 16.4 or later | Notification Center | Number on the Dock icon, icon bouncing | Supported |
| Linux | x64, Arm64; WebKitGTK 4.1 (2.40 or later), GTK 3 | WebKitGTK | Desktop notifications (freedesktop) | Numbers in desktop environments that support the Unity launcher API | Not yet |
- Tauri and Rust: Tauri 2.12 or later, Rust 1.90 or later.
- WebView2 runtime: included in Windows 11; on Windows 10 the Tauri installer downloads it. For intranets without internet access, bundle the WebView2 runtime in the installer (
bundle.windows.webviewInstallModein the Tauri config). - If the WebView falls short (for example no
OffscreenCanvasorcrypto.randomUUID), creating the client givesunsupported. Local storage and coordination between windows come from the plugin and don't rely on the WebView's IndexedDB, Web Locks or BroadcastChannel. - No Tauri mobile (iOS, Android): the plugin fails to compile for mobile. For phone apps, use the Flutter SDK.
- Platform: the SDK signs in as
windows,macosorlinuxbased on the system, and counts as a computer for per-platform device limits, in the same class as Flutter desktop and the Web SDK in Electron. If the app allows only one signed-in computer, signing in to the Tauri app signs the same account out on other computers, and vice versa. - Browsers are separate: on the same computer, a web page in a browser and the Tauri app are two devices that sign in separately and don't share local data.
Platform limits
- Linux:
- No audio or video calls yet:
im.calls.supportedisfalse, and placing or answering a call is rejected withunsupported(calls_unavailable). Incoming-call events are still emitted, so you can tell the user to answer on their phone. - Voice recording needs GStreamer encoders from the distribution. Without them,
im.files.recordVoice()is rejected withunsupported, so hide the record button. - Launcher numbers need the app's
.desktopfile to be installed on the system, see Badges. - Flatpak and Snap packaging aren't supported yet (notifications, file pickers and the keychain would need XDG portals); ship
.debor AppImage instead.
- No audio or video calls yet:
- Windows: system notifications require the app to be installed from an installer. During development, notifications from a directly run build appear to come from PowerShell and clicking them doesn't return to the app; see Packaging and signing.
- macOS: even apps that only send voice messages must declare a microphone usage description in
Info.plist, or the system terminates the app when recording starts; see Packaging and signing.
Core concepts
Engine window and UI windows
Desktop IM apps usually keep running in the tray after the user closes the main window and still alert on new messages. So the Tauri SDK keeps the connection in a hidden engine window that lives as long as the process and isn't affected by your window management:
- The engine window loads the engine page you provide. The plugin creates it at startup; it's never shown and doesn't appear in the taskbar. The engine holds the connection and the sign-in token, and handles sync, local writes, sending messages, and alerts and incoming calls when no window is visible.
- UI windows are your own windows, zero or more of them. Each window creates a client with
createDRTauriClient()and reads local data directly; the SDK forwards operations that need the server to the engine.
This works like multiple tabs sharing one connection in the Web SDK, except that the engine window is always the one holding the connection. See Engine and windows.
What's the same as the Web SDK
Subscribable lists (LiveList, MessageList), local-first storage with background sync, the send queue, and the event and error objects all match the Web SDK; see the Web SDK's Core concepts. Messages, conversations, groups and other returned objects have the same fields as in the server REST API.
Local data and tokens
Local data is stored in a SQLite database in the app data directory. The sign-in token is stored encrypted, with the key in the system keychain. Only the engine has the token; UI windows can't read it. See Tokens and local data.
How it works with your server
The same as the Web SDK: your server uses an App Token to create an IM account for the user and, after the user signs in to your system, issues a sign-in ticket. The app gets the ticket from your server and passes it to the SDK to sign in to IM; from then on, the SDK talks to the IM service directly to send and receive messages and sync conversations. The App Token and Client Secret are server credentials and must never be shipped in a desktop app.
The IM service's client APIs allow cross-origin calls, so desktop apps need no extra setup. File uploads and downloads go straight from the Rust plugin to file storage, so you don't need CORS rules on your file storage for desktop apps either.
Differences from the Web SDK
| Web SDK | Tauri SDK |
|---|---|
createDRClient(options) | Engine page: createDRTauriEngine(options); UI windows: createDRTauriClient({ appKey }) |
Options platform, deviceName | platform is set from the system; deviceName is an engine option and defaults to the computer name |
Options storage, tokenStorage, persistStorage, sessionScope | None: data is in SQLite, and the token is stored encrypted with its key in the system keychain |
| Tabs elect a primary tab | The engine window always holds the connection; im.connection.isLeader is always false in UI windows |
tabs.roleChanged | window.roleChanged: same payload, but only isAlertTab changes |
| You show browser notifications with the Notification API | System notifications, shown automatically by the SDK by default; see System notifications |
| "Viewing" requires the page to be visible | Also requires window focus: a window covered by another program doesn't count as viewing |
File parameters take a Blob | A Blob or a local path { path }; see Sending local files |
im.files.fetchBlob() downloads file contents | Still available and fine for small files; save large files to disk with im.desktop.download() |
| The send queue keeps attachments up to 50 MB | Attachments up to 200 MB are copied; larger ones are kept by path and sent after the app restarts |
| — | im.desktop and desktop events such as engine.stateChanged |
Not available yet
| Feature | Notes |
|---|---|
| Tauri on mobile (iOS, Android) | Use the Flutter SDK |
| Audio and video calls on Linux | See Platform limits |
| Offline push (APNs on macOS, WNS on Windows) | Desktop apps receive messages over the always-on connection; once the app quits, there are no alerts |
| A system incoming-call screen | Desktops have nothing like the phone call screen; incoming calls are shown by notifications and your windows |
| Tray icon and menu, launch at login, global shortcuts, screenshots | Use Tauri's tray API and its autostart, global shortcut and similar plugins; the SDK provides unread counts and a tray blinking helper, see Tray |
| UI components | Like the Web SDK, none are included |
| Sharing sign-in with web pages in a browser, migrating browser local data | They're different devices that sign in separately and sync from the server after signing in |
| Several accounts signed in at once | An AppKey has one signed-in user at a time; sign out before switching accounts |
App links (such as myapp://chat/…) | Receive them with Tauri's deep-link plugin, then open the conversation |
| Sender avatars and image thumbnails in notifications | Automatic notifications show only the app icon |
| Flatpak and Snap packaging on Linux | See Platform limits |
Standalone RTC channels
im.channels handles audio and video channels for meetings, voice rooms and other uses without a group. See Channels for the API, media permissions and foreground / background handling. Whether Linux's WebKitGTK includes WebRTC depends on the distribution; see Versions and support for platform support.