Installation and Setup

Relevant source files

The following files were used as context for generating this wiki page:

• README.md
• package.json
• Cargo.toml
• src/lib.rs
• guest-js/index.ts
• src/models.rs
• examples/tauri-app/src-tauri/tauri.conf.json

The Tauri Plugin Centrifugo provides a bridge between a Tauri-based application and a Centrifugo server for real-time, WebSocket-based communication. This plugin leverages the tokio-centrifuge Rust library to handle low-level network operations while exposing a high-level TypeScript/JavaScript API for frontend developers.

Installation involves configuring both the Rust backend and the JavaScript/TypeScript frontend. The setup process ensures that the Centrifugo client state is properly managed by the Tauri AppHandle and that the necessary permissions are granted for communication between the frontend and the underlying system.

Sources: README.md:1-20, src/lib.rs:1-15

Dependency Management

Automatic Installation

The recommended way to install the plugin is via the Tauri CLI, which automatically handles adding both the Rust crate and the NPM package to the project.

# Example using npm
npm run tauri add centrifugo

# Example using cargo
cargo tauri add centrifugo

Sources: README.md:22-42

Manual Backend Installation (Rust)

To manually add the plugin to the Rust backend, include tauri-plugin-centrifugo in the Cargo.toml file of the src-tauri directory.

[dependencies]
tauri-plugin-centrifugo = "0.1.2"

Sources: Cargo.toml:1-15, README.md:46-50

Manual Frontend Installation (JS/TS)

The frontend API is distributed via NPM as tauri-plugin-centrifugo-api.

npm install tauri-plugin-centrifugo-api

Sources: package.json:1-10, README.md:52-57

Backend Initialization

Initialization occurs in the main function of the Tauri application. The tauri_plugin_centrifugo::init() function registers the necessary command handlers and sets up the internal Centrifugo state manager.

Plugin Registration Flow

The following diagram illustrates how the plugin integrates into the Tauri lifecycle:

The init() function specifically registers commands such as connect, disconnect, publish, and rpc, while also managing the core::Centrifugo instance using Tauri's state management system.

Sources: src/lib.rs:65-95, README.md:65-72

Connection Configuration

The StartConfig structure is used to define the connection parameters. This configuration must be provided when calling the connect method from either the frontend or the backend.

StartConfig Specification

Field	Type	Description	Required
url	string	WebSocket URL for Centrifugo (e.g., ws://localhost:8000/connection/websocket)	Yes
token	string?	Optional JWT authentication token	No
name	string?	Optional client name identifier	No
channels	string[]	List of channels to subscribe to immediately	Yes
useProtobuf	boolean	If true, uses Protobuf protocol; otherwise JSON	Yes
readTimeout	number?	Timeout in milliseconds for read operations	No

Sources: src/models.rs:36-60, guest-js/index.ts:6-15

Permissions and Security

Tauri v2 requires explicit permission scoping for plugin commands. To enable the Centrifugo plugin, the centrifugo:default permission must be added to the application's capabilities configuration.

Capability Configuration

In src-tauri/capabilities/default.json:

{
  "permissions": [
    "centrifugo:default"
  ]
}

If permissions are not configured, the invoke calls to plugin commands will be blocked by the Tauri security layer.

Sources: README.md:358-375, examples/tauri-app/src-tauri/tauri.conf.json:10-15

Frontend Setup Example

Once installed and initialized, the plugin can be used in the frontend. The following sequence shows the standard setup flow for establishing a connection and listening for messages.

Basic Connection Code

import { connect, onConnected } from 'tauri-plugin-centrifugo-api';

// 1. Setup Listeners
await onConnected((event) => {
  console.log('Successfully connected at:', event.payload.ts);
});

// 2. Initiate Connection
await connect({
  url: 'ws://localhost:8000/connection/websocket',
  channels: ['chat', 'notifications'],
  useProtobuf: false
});

Sources: guest-js/index.ts:100-110, README.md:77-95

Summary

Setting up the Centrifugo plugin requires a two-step process: installing the dependencies (Cargo and NPM) and initializing the plugin within the Tauri builder. Security is managed through Tauri's capability system, and the connection is established using a standardized StartConfig object. This architecture ensures that the real-time connection persists within the Rust backend while providing a reactive interface to the frontend.