Tauri: wrap and package¶

Exercise tauri-wrap-and-package-annex.pdf · PDF

Your app is finished and documented. Your cousin wants to try it. What do you send? The repo link? Then your cousin has to install Node.js, npm and your dependencies before npm run dev does anything. And your grandmother?

A user wants one file: double-click, Next, Next, Finish, an icon in the menu. Until now your app has only run on a developer's machine. An app nobody can install is a prototype with good manners. This page gets it out of the workshop: you put your SvelteKit app in its own window, decide what travels with it, give it an icon and build your first package.

The suitcase¶

Keep one picture in your head for the whole page: packaging is packing a suitcase.

You are travelling to a house you have never seen. What you need and the house does not have goes in the suitcase. What the house already has, like a bed and running water, stays at home. Pack too little and you arrive without shoes. Pack the whole wardrobe and you pay for 100 kg.

Your app is the traveller. The user's computer is the house.

What Tauri is¶

Tauri is a tool that puts your web frontend in a native window. The window is drawn by the WebView the operating system already has, and a small program written in Rust opens it and talks to the system.

A WebView is a browser engine without the browser: no address bar, no tabs, only the part that draws HTML and CSS and runs JavaScript. Rust is a compiled programming language. You will read a few lines of it, and you do not need to learn it to package an app.

Tauri 2.0 came out on 2 October 2024, and it is the major version you use here. The official docs say that "a minimal Tauri app can be less than 600KB". That is possible because it does not carry a browser. The house already has the bed:

flowchart TB
    subgraph APP ["What you ship"]
        F["<b>Frontend</b><br>build/: HTML, CSS, JS<br>the clothes"]
        R["<b>Rust core</b><br>src-tauri/: opens the window, can touch files<br>the traveller's hands"]
        F <-->|"invoke(): JavaScript calls<br>a Rust function by name"| R
    end
    subgraph OS ["What the house already has"]
        W["<b>System WebView</b><br>draws your frontend<br>the bed"]
    end
    W -->|"draws"| F

The line between the two halves is a bridge. In Rust you mark a function as a command. In JavaScript you call it by name and wait for the answer:

#[tauri::command]
fn my_custom_command() {
    println!("I was invoked from JavaScript!");
}

#[cfg_attr(mobile, tauri::mobile_entry_point)]
pub fn run() {
    tauri::Builder::default()
        .invoke_handler(tauri::generate_handler![my_custom_command])
        .run(tauri::generate_context!())
        .expect("error while running tauri application");
}

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

invoke('my_custom_command');

The other way: Electron¶

Electron, the tool behind VS Code and Discord, packs its own copy of Chromium in every app. The bed travels in the suitcase.

Tauri's price is on the last row. If you only tested your app in Chrome, some things will look different in the Tauri window on Linux: a font, a scrollbar, a date input. Look for those differences on purpose.

Before you start: the toolchain¶

Building a Tauri app needs Rust and some system libraries. Your classroom PC already has them. To work at home, install them once.

sudo apt install libwebkit2gtk-4.1-dev build-essential curl wget file libxdo-dev libssl-dev libayatana-appindicator3-dev librsvg2-dev
curl --proto '=https' --tlsv1.2 https://sh.rustup.rs -sSf | sh

winget install --id Rustlang.Rustup
rustup default stable-msvc

Once a project is wrapped, npm run tauri info prints a report of what your machine has and what is missing.

Wrapping a SvelteKit app in six steps¶

Do this on a new git branch, for example tauri, in your project from Unit 3 and later. The example on this page is NoteBox, a tiny notes app.

1. Install the tools.

npm install -D @sveltejs/adapter-static @tauri-apps/cli
npm install @tauri-apps/api

2. Export static files. There is no server inside a window, so SvelteKit must produce plain files. An adapter is the SvelteKit plugin that shapes the build for the place it will run, and adapter-static writes a folder of plain files called build/. Find where your project says adapter-auto and replace it. Where it says so depends on how old your project template is:

import adapter from '@sveltejs/adapter-static';
import { sveltekit } from '@sveltejs/kit/vite';
import { defineConfig } from 'vite';

export default defineConfig({
    plugins: [
        sveltekit({
            adapter: adapter({ fallback: 'index.html' })
        })
    ]
});

import adapter from '@sveltejs/adapter-static';
import { vitePreprocess } from '@sveltejs/vite-plugin-svelte';

/** @type {import('@sveltejs/kit').Config} */
const config = {
    preprocess: vitePreprocess(),
    kit: {
        adapter: adapter({ fallback: 'index.html' })
    }
};

export default config;

Keep any other options your file already has. The fallback is the one HTML page that loads your app and then shows the right route. Without it, the window has nothing to open.

3. Render in the WebView, not on a server. Create src/routes/+layout.js with one line:

export const ssr = false;

4. Add a shortcut for the command-line tool. In package.json, under scripts:

"tauri": "tauri"

5. Create the native half.

npm run tauri init

It asks six questions:

6. Run it in its own window.

npm run tauri dev

The first run compiles about 400 Rust packages, called crates. Expect several minutes. Do something else while it runs. Then a window appears, with no address bar, no tabs and its own entry in the taskbar. It is your app.

When it goes wrong¶

The label on the suitcase¶

tauri init created a new folder. Four things in it matter for now:

Open tauri.conf.json and read the label:

Change two of them before you build:

• Set identifier to something of yours, such as com.iessonferrer.notebox. A reverse domain is a web domain written backwards. It can only contain letters, digits, hyphens and dots. Leave the default com.tauri.dev and tauri build refuses to start.
• Set version to 0.1.0. It ends up in the file name of the package.

What goes in the box?¶

Your project folder is huge. The installer is tiny. So what travels?

node_modules is the kitchen. The installer carries the dish.

Two rows deserve a second look:

• WebView2. By default, the Windows installer does not carry it. If it is missing, the installer downloads a small program, the bootstrapper, that installs it. Carrying the full offline installer inside your package adds about 127 MB.
• The user's notes. They do not exist yet when you install. They are created later, on the user's disk. You will meet them again when you uninstall.

The missing file¶

NoteBox reads its welcome notes from src-tauri/resources/welcome-notes.json, through a Rust command. In tauri dev it works. Then you run the release program from another folder, and a yellow panel says "Welcome notes not found".

What changed? In dev, the app reads from your project folder, where every file is at hand. A packaged app only has what was packed. You arrived without shoes.

The fix is one line of the label, in bundle > resources:

"bundle": {
  "active": true,
  "targets": "all",
  "resources": ["resources/welcome-notes.json"],
  "icon": ["icons/32x32.png", "icons/128x128.png", "icons/128x128@2x.png", "icons/icon.icns", "icons/icon.ico"]
}

Paths are relative to src-tauri/. Patterns work too: "resources/**/*" takes every file in that folder and its subfolders.

In the installed app the file lands in the resource folder: /usr/lib/NoteBox/resources/ in our .deb, and next to the .exe on Windows. The path changes per system, so your Rust code never writes it by hand. It asks Tauri instead:

handle.path().resolve("resources/welcome-notes.json", BaseDirectory::Resource)

The app icon¶

A package with the default Tauri icon says "unfinished" before the app even opens. So design one in Figma, in a 1024 × 1024 frame.

• One shape, and two or three flat colours.
• No text.
• Transparent outside the tile.
• Keep the subject inside a safe area, away from the edges.
• Look at it at 128, 32 and 16 px. If your neighbour cannot say what it is at 16 px, remove detail. Do not add it.

Export the frame as PNG at 1x and save it as app-icon.png in the project root. Then run one command:

npm run tauri icon

It reads ./app-icon.png, a square PNG or SVG with transparency, and writes the whole set to src-tauri/icons/:

There is nothing to edit afterwards: bundle > icon already lists these files.

Your first package¶

npm run tauri build

This one command does three things:

flowchart LR
    A["<b>npm run build</b><br>the frontend<br>into build/"] --> B["<b>Rust compile</b><br>release mode<br>the program"]
    B --> C["<b>Bundler</b><br>packs everything for<br>the current system"]
    C --> D["<b>Packages</b><br>src-tauri/target/<br>release/bundle/"]

The bundler is the part of Tauri that makes the packages. On Ubuntu it makes a .deb, an .rpm and an .AppImage. To go faster, ask for one:

npm run tauri build -- --bundles deb

The extra -- tells npm that what follows belongs to Tauri, not to npm.

Release mode is a different build from dev, so everything compiles again. Expect several more minutes. When it ends, the last lines print the path:

NoteBox's .deb weighs 2.9 MB. Try it on your own computer: double-click the file, or run sudo apt install ./NoteBox_0.1.0_amd64.deb with your own file name.

Key takeaways¶

• Tauri puts your web frontend in a native window. The system WebView draws it and a small Rust core opens it, so no browser travels in the package.
• Wrapping a SvelteKit app takes adapter-static with a fallback, ssr = false, then tauri init and tauri dev. Server-only code cannot come along.
• tauri.conf.json is the label on the suitcase. The identifier must be your own, in reverse-domain form, and it names the user's data folder.
• node_modules is the kitchen and the installer carries the dish. Only build/, the Rust program, the icons and what you list in bundle > resources travel.
• tauri icon makes every icon size from one square image.
• tauri build makes packages for the current system only. Test the installed package, not tauri dev.

Quick check¶

You have a package now, but its installer still looks like nobody's. Next you design what the user sees between the double-click and the first screen: Installers and the wizard.