Tauri Plugin BareKit

Write your backend logic once in JavaScript and have it run effortlessly run across Android, iOS, macOS, Windows, and Linux. No sidecar needed, no complex configuration, no headaches 🐼

About Bare and BareKit

Bare

Bare is, in the words of it's creators:

"Small and modular JavaScript runtime for desktop and mobile" - Holepunch Inc.

You can think of Bare as a mini-node, though it's actually much more than that. Bare was created with the goal of running JavaScript on mobile efficiently, without losing support for desktop platforms. Thus it's highly embeddable and treats every platform as a first class citizen.

Bare was built on V8 and libuv, similar to Node. What's more, Bare has built-in support for N-API modules, in addition to it's own addon system. Thus you can make use of the sizable and growing Bare ecosystem or use the vast majority of modules available on NPM.

BareKit

BareKit is an SDK for Bare for native application development. It makes embedding Bare in your application almost trivial.

<BareKit> [...] provides a web worker-like API to start and manage isolated Bare threads, called worklets, that expose an IPC abstraction with bindings for various languages.

This plugin

tauri-plugin-bare-kit provides BareKit bindings for rust through FFI and exposes familiar worker API for running Bare worklets to Tauri frontend.

It also provides autolinking of native addons for JavaScript to avoid headaches and frustrations for users (DevEx matters!), so you can just tauri add bare-kit and start installing packages from NPM and writing your code. When you've built your app, everything will be included and correctly linked.

Installation

Prerequisites:

• Node/npm
• Clang

Then just:

tauri add bare-kit

Note about iOS

Tauri's iOS build heavily depends on XCode so autolinking is trickier to implement. If you haven't yet generated iOS project at the time you install tauri-plugin-bare-kit xcodebuild will fail to find BareKit. Just delete node_modules and run npm install again after generating iOS project and everything should work.

Usage

import { Worklet } from "tauri-plugin-bare-kit-api"
import b4a from "b4a"
// import bundle from "../app.bundle.json"

const worklet = await Worklet.init({ assets, memoryLimit })
const bundle = `
const { IPC } = BareKit
IPC.on("data", (data) => console.log(b4a.toString(data)))
IPC.write(b4a.from("Hello from Bare!"))
`

await worklet.start("/app.bundle", bundle, args)

const { IPC } = worklet

IPC.on("data", (data) => console.log(b4a.toString(data)))
IPC.write(b4a.from("Hello from Tauri!"))

This will log Hello from Tauri! to the operating system log and Hallo from Bare! to Tauri's devtools console.

For this plugin to find your entry point and generate a bundle for Bare, it looks for a file called app.js in several locations. First it looks for a folder in your project's root (next to package.json and src-tauri) called bare (Bare convention) or src-bare (Tauri convention). If this folder contains folders src or dist (in case you're transpiling your sources, e.g. TypeScript) it looks in them too. Using the entry point, this plugin traverses node_modules to collect dependencies and produces a single file bundle in your root folder called app.bundle.json and dependency manifest app.bundle.json.d. You should add these files to your .gitignore. The JSON file is just a single JSON string containing the entire stringified bundle that you should import on your frontend and pass to Bare worklet.

API

import { Worklet }

The primary interface for starting, stopping, suspending, and resuming Bare. Because Tauri IPC is asynchronous, you MUST NOT instantiate this class directly (e.g. via new Worklet()). Instead use the init(...) static method.

const worklet = Worklet.init(options)

Instantiates a new Bare worklet on a worker thread.

Options include:

  assets: string,
  memoryLimit: number,

Worklet is also an event emitter. Available events include:

event: start | terminate | suspend | resume | wakeup

await Worklet.suspend(linger)

Suspend all worklets stopping all I/O. It's important to suspend the worklets when app enters background, because on mobile operating system might kill the app otherwise.

// How much time the worklets have to stop I/O
linger: number

await Worklet.resume()

Exit suspended state and resume I/O for all worklets.

await Worklet.wakeup(deadline)

Temporalily wake suspended worklets to perform additional work (e.g. handle a notification).

// Time allocated to perform given task
deadline: number

worklet.IPC

The bidirectional IPC interface. It inherits from streamx.Duplex and has a similar API to node streams.

worklet.started

boolean indicating if worklet.start(...) has been called.

worklet.terminated

boolean indicating if worklet.terminate() has been called.

worklet.suspended

boolean indicating current state of the worklet.

await worklet.start(filename, source, args)

Start the worklet. After this method succeeds IPC becomes available.

Arguments are:

// Either a file on disk to use as source or dummy path to indicate the type of source
// It should always end in .bundle
filename: string
// The source to execute. If you're providing a real path to filename argument
// set this to null
source: string | Uint8Array | null
// The command line flags to pass to Bare/V8
args: string[]

You should provide dummy path to filename such as /app.bundle and actual sources through source argument if you want to support mobile. Reading sources from filesystem can be problematic, because such access is restricted and could potentially violate app store policies.

await worklet.suspend(linger)

Suspend the worklet stopping all I/O. It's important to suspend the worklet when app enters background, because on mobile operating system might kill the app otherwise.

// How much time the worklet has to stop I/O
linger: number

await worklet.resume()

Exit suspended state and resume I/O.

await worklet.wakeup(deadline)

Temporalily wake suspended worklet to perform additional work (e.g. handle a notification).

// Time allocated to perform given task
deadline: number

await worklet.terminate()

Stop and destroy worklet freeing resources.

Logging

BareKit uses liblog as logging provider. You can read more on how to access the logs there.

License

Apache-2.0