core

Invoke your custom commands.

This package is also accessible with window.__TAURI__.core when app.withGlobalTauri in tauri.conf.json is set to true.

Classes

Channel

Source: https://github.com/tauri-apps/tauri/blob/dev/packages/api/src/core.ts#L119

A message channel used to stream values from Rust to the frontend.

A Channel is the JavaScript counterpart of tauri::ipc::Channel. Pass an instance as a command argument and the Rust command can declare a tauri::ipc::Channel<T> parameter with the same name; every value sent from Rust is then delivered to Channel.onmessage. Messages are delivered in the order they were sent, even when they arrive out of order.

The channel stays alive until the Rust Channel is dropped, so it can be used for long-running work such as download progress or log streaming.

Raw byte payloads are delivered to the frontend as an ArrayBuffer rather than a JSON value, so declare the channel as Channel<ArrayBuffer> when the Rust side sends tauri::ipc::InvokeResponseBody::Raw — for example through a Channel<tauri::ipc::Response> whose values are built with tauri::ipc::Response::new(bytes).

Example

import { Channel, invoke } from '@tauri-apps/api/core';

const onEvent = new Channel<string>();
onEvent.onmessage = (message) => {
  console.log(`got download event ${message}`);
};

await invoke('download', { url: 'https://tauri.app', onEvent });

The matching Rust command:

#[tauri::command]
async fn download(url: String, on_event: tauri::ipc::Channel<String>) -> tauri::Result<()> {
  on_event.send("started".to_string())?;
  on_event.send("finished".to_string())?;
  Ok(())
}

Since

2.0.0

Type Parameters

Type Parameter	Default type
T	unknown

Constructors

Constructor

new Channel<T>(onmessage?): Channel<T>;

Source: https://github.com/tauri-apps/tauri/blob/dev/packages/api/src/core.ts#L134

Parameters

Parameter	Type
onmessage?	(response) => void

Returns

Channel<T>

Properties

Property	Type	Description	Defined in
id	number	The callback id returned from transformCallback. This is the value sent across the IPC, it is used by the Rust side to address this channel and should not be changed.	Source: https://github.com/tauri-apps/tauri/blob/dev/packages/api/src/core.ts#L126

Accessors

onmessage

Get Signature

get onmessage(): (response) => void;

Source: https://github.com/tauri-apps/tauri/blob/dev/packages/api/src/core.ts#L196

Returns

(response) => void

Set Signature

set onmessage(handler): void;

Source: https://github.com/tauri-apps/tauri/blob/dev/packages/api/src/core.ts#L192

The handler called for every message sent by the Rust side of this channel.

Assigning a new handler replaces the previous one; messages that arrived before a handler was set are not replayed, so set it (or pass it to the constructor) before sending the channel to the backend.

Parameters

Parameter	Type
handler	(response) => void

Returns

void

Methods

__TAURI_TO_IPC_KEY__()

__TAURI_TO_IPC_KEY__(): string;

Source: https://github.com/tauri-apps/tauri/blob/dev/packages/api/src/core.ts#L200

Returns

string

toJSON()

toJSON(): string;

Source: https://github.com/tauri-apps/tauri/blob/dev/packages/api/src/core.ts#L204

Returns

string

---

PluginListener

Source: https://github.com/tauri-apps/tauri/blob/dev/packages/api/src/core.ts#L219

A handle to a listener registered with addPluginListener.

Keep the returned instance around and call PluginListener.unregister when the listener goes out of scope, otherwise the plugin keeps sending events to a handler nothing uses anymore.

Since

2.0.0

Constructors

Constructor

new PluginListener(
   plugin,
   event,
   channelId
): PluginListener;

Source: https://github.com/tauri-apps/tauri/blob/dev/packages/api/src/core.ts#L227

Parameters

Parameter	Type
plugin	string
event	string
channelId	number

Returns

PluginListener

Properties

Property	Type	Description	Defined in
channelId	number	The id of the Channel backing this listener.	Source: https://github.com/tauri-apps/tauri/blob/dev/packages/api/src/core.ts#L225
event	string	The plugin event name the listener is registered to.	Source: https://github.com/tauri-apps/tauri/blob/dev/packages/api/src/core.ts#L223
plugin	string	The plugin name the listener is registered to.	Source: https://github.com/tauri-apps/tauri/blob/dev/packages/api/src/core.ts#L221

Methods

unregister()

unregister(): Promise<void>;

Source: https://github.com/tauri-apps/tauri/blob/dev/packages/api/src/core.ts#L234

Removes this listener from the plugin, so its handler stops being called.

Returns

Promise<void>

---

Resource

Source: https://github.com/tauri-apps/tauri/blob/dev/packages/api/src/core.ts#L544

A rust-backed resource stored through tauri::Manager::resources_table API.

The resource lives in the main process and does not exist in the Javascript world, and thus will not be cleaned up automatically except on application exit. If you want to clean it up early, call Resource.close or use Explicit Resource Management.

Several API types are resources and inherit this behavior, among them Menu, TrayIcon, Image, Webview and the menu item classes.

To support older browsers with Explicit Resource Management, use a supported compiler (e.g. tsc) or bundler (e.g. rollup).

Examples

import { Resource, invoke } from '@tauri-apps/api/core';

export class DatabaseHandle extends Resource {
  static async open(path: string): Promise<DatabaseHandle> {
    const rid: number = await invoke('open_db', { path });
    return new DatabaseHandle(rid);
  }

  async execute(sql: string): Promise<void> {
    await invoke('execute_sql', { rid: this.rid, sql });
  }
}

Only asynchronous disposal is implemented (Symbol.asyncDispose), because closing a resource is an IPC call. Use await using; the synchronous using form does not work with resources.

await using db = await DatabaseHandle.open('test.db');
await db.execute('SELECT *');
// `db` is closed here, by awaiting `db[Symbol.asyncDispose]()`

To support older browsers, add the following to the globals (e.g. adding to the HTML file):

Symbol.asyncDispose ??= Symbol("Symbol.asyncDispose");

And for the compiler, for example tsc, rollup, vite, add the following to tsconfig.json:

{
  "compilerOptions": {
    "target": "es2022",
    "lib": ["es2022", "esnext.disposable", "dom"]
  }
}

Extended by

• Image
• TrayIcon

Constructors

Constructor

new Resource(rid): Resource;

Source: https://github.com/tauri-apps/tauri/blob/dev/packages/api/src/core.ts#L551

Parameters

Parameter	Type
rid	number

Returns

Resource

Accessors

rid

Get Signature

get rid(): number;

Source: https://github.com/tauri-apps/tauri/blob/dev/packages/api/src/core.ts#L547

Returns

number

Methods

[asyncDispose]()

asyncDispose: Promise<void>;

Source: https://github.com/tauri-apps/tauri/blob/dev/packages/api/src/core.ts#L568

Returns

Promise<void>

close()

close(): Promise<void>;

Source: https://github.com/tauri-apps/tauri/blob/dev/packages/api/src/core.ts#L562

Destroys and cleans up this resource from memory. You should not call any method on this object anymore and should drop any reference to it.

Returns

Promise<void>

Remarks

Uses the core:resources:allow-close permission, which is part of the core:resources:default permission set enabled by default.

Interfaces

InvokeOptions

Source: https://github.com/tauri-apps/tauri/blob/dev/packages/api/src/core.ts#L395

Since

2.0.0

Properties

Property	Type	Description	Defined in
headers	HeadersInit	Headers to send along with the IPC request. They are readable on the Rust side through tauri::ipc::Request::headers and are useful to pass metadata (such as a content type for a raw payload) without adding it to the command arguments. Example import { invoke } from '@tauri-apps/api/core'; await invoke('upload', new Uint8Array([1, 2, 3]), { headers: { 'x-file-name': 'image.png' } });	Source: https://github.com/tauri-apps/tauri/blob/dev/packages/api/src/core.ts#L412

Type Aliases

InvokeArgs

type InvokeArgs =
  | Record<string, unknown>
  | number[]
  | ArrayBuffer
  | Uint8Array;

Source: https://github.com/tauri-apps/tauri/blob/dev/packages/api/src/core.ts#L390

Command arguments.

An object is the usual form: each key becomes a command parameter, serialized as JSON (application/octet-stream is used instead when a value implements SERIALIZE_TO_IPC_FN, see its documentation).

The ArrayBuffer, Uint8Array and number[] variants are a raw payload: the whole request body is sent as application/octet-stream instead of JSON, which avoids the cost of base64/array encoding for large binary data. The command then has a single tauri::ipc::Request parameter and reads the bytes from it:

#[tauri::command]
fn upload(request: tauri::ipc::Request<'_>) -> Result<(), String> {
  let tauri::ipc::InvokeBody::Raw(bytes) = request.body() else {
    return Err("expected a raw body".into());
  };
  println!("got {} bytes", bytes.len());
  Ok(())
}

import { invoke } from '@tauri-apps/api/core';
await invoke('upload', new Uint8Array([1, 2, 3]));

A command that returns tauri::ipc::Response likewise resolves to an ArrayBuffer on the frontend instead of a JSON value.

Since

1.0.0

---

PermissionState

type PermissionState = "granted" | "denied" | "prompt" | "prompt-with-rationale";

Source: https://github.com/tauri-apps/tauri/blob/dev/packages/api/src/core.ts#L294

Variables

SERIALIZE_TO_IPC_FN

const SERIALIZE_TO_IPC_FN: "__TAURI_TO_IPC_KEY__" = '__TAURI_TO_IPC_KEY__';

Source: https://github.com/tauri-apps/tauri/blob/dev/packages/api/src/core.ts#L59

A key to be used to implement a special function on your types that define how your type should be serialized when passing across the IPC.

Example

Given a type in Rust that looks like this

#[derive(serde::Serialize, serde::Deserialize)
enum UserId {
  String(String),
  Number(u32),
}

UserId::String("id") would be serialized into { String: "id" } and so we need to pass the same structure back to Rust

import { SERIALIZE_TO_IPC_FN } from "@tauri-apps/api/core"

class UserIdString {
  id
  constructor(id) {
    this.id = id
  }

  [SERIALIZE_TO_IPC_FN]() {
    return { String: this.id }
  }
}

class UserIdNumber {
  id
  constructor(id) {
    this.id = id
  }

  [SERIALIZE_TO_IPC_FN]() {
    return { Number: this.id }
  }
}

type UserId = UserIdString | UserIdNumber

Functions

addPluginListener()

function addPluginListener<T>(
   plugin,
   event,
   cb
): Promise<PluginListener>;

Source: https://github.com/tauri-apps/tauri/blob/dev/packages/api/src/core.ts#L274

Adds a listener to a plugin event.

This is meant to be used by plugin authors to wrap the register_listener command their mobile plugin implements; application code normally calls the wrapper the plugin exposes instead of this function.

Type Parameters

Type Parameter
T

Parameters

Parameter	Type	Description
plugin	string	The plugin name, as used in the `plugin:
event	string	The plugin event name.
cb	(payload) => void	The callback executed for each event payload.

Returns

Promise<PluginListener>

The listener object to stop listening to the events.

Example

import { addPluginListener } from '@tauri-apps/api/core';

interface ScanEvent {
  value: string
}

const listener = await addPluginListener<ScanEvent>(
  'barcode-scanner',
  'scan',
  (payload) => console.log('scanned', payload.value)
);

// stop listening when the scanner screen is closed
await listener.unregister();

Since

2.0.0

---

checkPermissions()

function checkPermissions<T>(plugin): Promise<T>;

Source: https://github.com/tauri-apps/tauri/blob/dev/packages/api/src/core.ts#L322

Get permission state for a plugin.

This should be used by plugin authors to wrap their actual implementation, it calls the plugin:<name>|check_permissions command implemented by the mobile plugin and returns its permission status object without prompting the user.

Type Parameters

Type Parameter
T

Parameters

Parameter	Type	Description
plugin	string	The plugin name, as used in the `plugin:

Returns

Promise<T>

Example

import { checkPermissions, type PermissionState } from '@tauri-apps/api/core';

interface Permissions {
  camera: PermissionState
}

const status = await checkPermissions<Permissions>('barcode-scanner');
if (status.camera === 'prompt') {
  // ask the user, see requestPermissions
}

Since

2.0.0

---

convertFileSrc()

function convertFileSrc(filePath, protocol?): string;

Source: https://github.com/tauri-apps/tauri/blob/dev/packages/api/src/core.ts#L482

Convert a device file path to a URL that can be loaded by the webview.

The asset protocol must be enabled and the files you want to expose must be included in its scope. The protocol origins must also be allowed by the relevant app.security.csp directive. For example, this configuration allows images from the user’s downloads directory:

{
  "app": {
    "security": {
      "assetProtocol": {
        "enable": true,
        "scope": ["$DOWNLOAD/**"]
      },
      "csp": "default-src 'self'; img-src 'self' asset: http://asset.localhost"
    }
  }
}

See assetProtocol for the available scope variables and platform-specific protocol details.

Parameters

Parameter	Type	Default value	Description
filePath	string	undefined	The file path.
protocol	string	'asset'	The protocol to use. Defaults to asset. You only need to set this when using a custom protocol.

Returns

string

the URL that can be used as source on the webview.

Example

import { downloadDir, join } from '@tauri-apps/api/path';
import { convertFileSrc } from '@tauri-apps/api/core';
const downloads = await downloadDir();
const filePath = await join(downloads, 'photo.png');
const assetUrl = convertFileSrc(filePath);

const image = document.getElementById('my-image') as HTMLImageElement;
image.src = assetUrl;

Since

1.0.0

---

invoke()

function invoke<T>(
   cmd,
   args?,
   options?
): Promise<T>;

Source: https://github.com/tauri-apps/tauri/blob/dev/packages/api/src/core.ts#L430

Sends a message to the backend.

Type Parameters

Type Parameter
T

Parameters

Parameter	Type	Description
cmd	string	The command name.
args	InvokeArgs	The optional arguments to pass to the command.
options?	InvokeOptions	The request options.

Returns

Promise<T>

A promise resolving or rejecting to the backend response.

Example

import { invoke } from '@tauri-apps/api/core';
await invoke('login', { user: 'tauri', password: 'poiwe3h4r5ip3yrhtew9ty' });

Since

1.0.0

---

isTauri()

function isTauri(): boolean;

Source: https://github.com/tauri-apps/tauri/blob/dev/packages/api/src/core.ts#L592

Checks whether the code is running inside a Tauri webview.

Useful for frontends that are also served on the web, to guard calls to APIs that only exist inside the application.

Returns

boolean

true when running inside a Tauri app, false otherwise (e.g. in a browser or in unit tests).

Example

import { isTauri } from '@tauri-apps/api/core';
import { getVersion } from '@tauri-apps/api/app';

const version = isTauri() ? await getVersion() : 'web';

Since

2.0.0

---

requestPermissions()

function requestPermissions<T>(plugin): Promise<T>;

Source: https://github.com/tauri-apps/tauri/blob/dev/packages/api/src/core.ts#L352

Request permissions.

This should be used by plugin authors to wrap their actual implementation, it calls the plugin:<name>|request_permissions command implemented by the mobile plugin, which shows the native permission prompt when needed, and returns the resulting permission status object.

Type Parameters

Type Parameter
T

Parameters

Parameter	Type	Description
plugin	string	The plugin name, as used in the `plugin:

Returns

Promise<T>

Example

import { requestPermissions, type PermissionState } from '@tauri-apps/api/core';

interface Permissions {
  camera: PermissionState
}

const status = await requestPermissions<Permissions>('barcode-scanner');
if (status.camera !== 'granted') {
  throw new Error('camera permission denied');
}

Since

2.0.0

---

transformCallback()

function transformCallback<T>(callback?, once?): number;

Source: https://github.com/tauri-apps/tauri/blob/dev/packages/api/src/core.ts#L69

Stores the callback in a known location, and returns an identifier that can be passed to the backend. The backend uses the identifier to eval() the callback.

Type Parameters

Type Parameter	Default type
T	unknown

Parameters

Parameter	Type	Default value
callback?	(response) => void	undefined
once?	boolean	false

Returns

number

An unique identifier associated with the callback function.

Since

1.0.0