tauri-apps/tauri
1
1
Fork 0
mirror of https://github.com/tauri-apps/tauri.git synced 2024-09-11 07:55:34 +03:00
Code Issues Packages Projects Releases Wiki Activity

Docs removal (#3263)

Browse Source
This commit is contained in:
Lorenzo Lewis 2022-01-23 19:48:42 +00:00 committed by GitHub
parent 18aab872a9
commit 75dea8bd39
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
54 changed files with 1 additions and 5386 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

0
docs/splash.png → .github/splash.png vendored
View File

Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 59 KiB

After

Width:  |  Height:  |  Size: 59 KiB

6
.github/workflows/update-docs.yml vendored
View File

@ -68,12 +68,6 @@ jobs:
- name: Copy JS docs
run: cp -r tauri/tooling/api/docs/* tauri-docs/docs/api/js/
- name: Copy Architecture doc
run: cp -r tauri/ARCHITECTURE.md tauri-docs/docs/about/
- name: Copy Guides docs
run: rsync -avr --exclude '.templates' tauri/docs/ tauri-docs/docs/
# Indexing
- name: meilisearch indexation

0
docs/.templates/cli.md → .scripts/covector/templates/cli.md
View File

0
docs/.templates/config.md → .scripts/covector/templates/config.md
View File

2
README.md
View File

@ -1,4 +1,4 @@
<img src="docs/splash.png" alt="Tauri" />
<img src=".github/splash.png" alt="Tauri" />
[![status](https://img.shields.io/badge/Status-Beta-green.svg)](https://github.com/tauri-apps/tauri/tree/dev)
[![License](https://img.shields.io/badge/License-MIT%20or%20Apache%202-green.svg)](https://opencollective.com/tauri)

191
docs/api/cli.md
View File

@ -1,191 +0,0 @@
---
id: cli
title: CLI
---
import Command from '@theme/Command'
import Alert from '@theme/Alert'
The tauri.js cli is composed in TypeScript and published as JavaScript.
## `info`
<Command name="info" />
```
Description
Returns the known state of tauri dependencies and configuration
```
It shows a concise list of information about the environment, Rust, Node.js and their versions as well as some relevant configurations.
<Alert title="Note" icon="info-alt">
This command is pretty helpful when you need to have a quick overview of your application. When requesting some help, it can be useful that you share this report with us.
</Alert>
## `init`
<Command name="init" />
```
Initializes a Tauri project
USAGE:
cargo tauri init [FLAGS] [OPTIONS] [SUBCOMMAND]
FLAGS:
--ci Skip prompting for values
-f, --force Force init to overwrite the src-tauri folder
-h, --help Print help information
-l, --log Enables logging
-V, --version Print version information
OPTIONS:
-A, --app-name <app-name> Name of your Tauri application
-d, --directory <directory> Set target directory for init
-D, --dist-dir <dist-dir> Web assets location, relative to <project-dir>/src-tauri
-P, --dev-path <dev-path> Url of your dev server
-t, --tauri-path <tauri-path> Path of the Tauri project to use (relative to the cwd)
-W, --window-title <window-title> Window title of your Tauri application
SUBCOMMANDS:
help Print this message or the help of the given subcommand(s)
plugin Initialize a Tauri plugin.
```
### `init plugin`
<Command name="init plugin" />
```
Initializes a Tauri plugin project.
USAGE:
cargo tauri init plugin [FLAGS] [OPTIONS] --name <name>
FLAGS:
-a, --api Initializes a Tauri plugin with TypeScript API.
-h, --help Print help information
-V, --version Print version information
OPTIONS:
-d, --directory <directory> Set target directory for init
-n, --name <name> Name of your Tauri plugin
-t, --tauri-path <tauri-path> Path of the Tauri project to use (relative to the cwd)
```
## `dev`
<Command name="dev" />
```
Tauri dev.
USAGE:
cargo tauri dev [FLAGS] [OPTIONS] [--] [args]...
ARGS:
<args>... Args passed to the binary
FLAGS:
-e, --exit-on-panic Exit on panic
-h, --help Print help information
--release Run the code in release mode
-V, --version Print version information
OPTIONS:
-c, --config <config> config JSON to merge with tauri.conf.json
-f, --features <features>... list of cargo features to activate
-r, --runner <runner> binary to use to run the application
-t, --target <target>... target triple to build against
```
This command will open the WebView in development mode. It makes use of the `build.devPath` property from your `src-tauri/tauri.conf.json` file.
If you have entered a command to the `build.beforeDevCommand` property, this one will be executed before the `dev` command.
<a href="/docs/api/config#build">See more about the configuration.</a><br/><br/>
<Alert title="Troubleshooting" type="warning" icon="alert">
If you're not using `build.beforeDevCommand`, make sure your `build.devPath` is correct and, if using a development server, that it's started before using this command.
</Alert>
## `deps`
<Command name="deps update" />
```sh
Description
Tauri dependency management script
Usage
$ tauri deps [install|update]
```
## `build`
<Command name="build" />
```
Tauri build.
USAGE:
cargo tauri build [FLAGS] [OPTIONS]
FLAGS:
-d, --debug Builds with the debug flag
-h, --help Print help information
-v, --verbose Enables verbose logging
-V, --version Print version information
OPTIONS:
-b, --bundle <bundle>... list of bundles to package
-c, --config <config> config JSON to merge with tauri.conf.json
-f, --features <features>... list of cargo features to activate
-r, --runner <runner> binary to use to build the application
-t, --target <target>... target triple to build against
```
This command will bundle your application, either in production mode or debug mode if you used the `--debug` flag. It makes use of the `build.distDir` property from your `src-tauri/tauri.conf.json` file.
If you have entered a command to the `build.beforeBuildCommand` property, this one will be executed before the `build` command.
<a href="/docs/api/config#build">See more about the configuration.</a>
## `icon`
<Command name="icon" />
```
Description
Create all the icons you need for your Tauri app.
Usage
$ tauri icon /path/to/icon.png
Options
--help, -h Displays this message
--log, -l Logging [boolean]
--target, -t Target folder (default: 'src-tauri/icons')
--compression, -c Compression type [optipng|zopfli]
--ci Runs the script in CI mode
```
This command will generate a set of icons, based on the source icon you've entered. Note that the source icon must be 1240x1240 with transparency.
## `version`
<Command name="--version" />
```
Description
Returns the current version of tauri
```
This command will show the current version of Tauri.
## CLI usage
See more about the usage through this [complete guide](/docs/development/integration).

386
docs/api/config.md
View File

@ -1,386 +0,0 @@
---
title: Configuration
---
import Properties from '@theme/Properties'
import Array from '@theme/Array'
import Alert from '@theme/Alert'
The `tauri.conf.json` is a file generated by the `tauri init` command (see <a href="/docs/api/cli#tauri-init">here</a>) that lives in your Tauri application source directory (src-tauri).
Once generated, you may modify it at will to customize your Tauri application.
# Platform-specific configuration
In addition to the JSON defined on the `tauri.conf.json` file, Tauri reads a platform-specific configuration on `tauri.linux.conf.json`, `tauri.windows.conf.json` and `tauri.macos.conf.json` and merges it with the main `tauri.conf.json` configuration.
# Configuration structure
`tauri.conf.json` is composed of the following properties:
## `build`
<Properties anchorRoot="build" rows={[
{property: "distDir", type: "string", description: `The path to the production-ready webpage/webapp directory (either absolute or relative to tauri.conf.json) that will be bundled by Tauri.
<div class="alert alert--info" role="alert" style="margin-top: 10px;">
The target directory <em>must</em> contain an index.html file.
</div>`},
{property: "devPath", type: "string", description: `Can be a path to a folder (either absolute or relative to tauri.conf.json) or a URL (like a live reload server).`},
{property: "beforeDevCommand", optional: true, type: "string", description: `A command to run before starting Tauri in dev mode. The PLATFORM, ARCH, FAMILY and PLATFORM_TYPE environment variables are set if you perform conditional compilation.`},
{property: "beforeBuildCommand", optional: true, type: "string", description: `A command to run before starting Tauri's build pipeline. The PLATFORM, ARCH, FAMILY and PLATFORM_TYPE environment variables are set if you perform conditional compilation.`},
{property: "withGlobalTauri", optional: true, type: "boolean", description: "Enables the API injection to the window.__TAURI__ object. Useful if you're using Vanilla JS instead of importing the API using Rollup or Webpack. Reduces the command security since any external code can access it, so be careful with XSS attacks."}
]}/>
```js title=Example
"build": {
"distDir": "../dist",
"devPath": "http://localhost:4000",
"beforeDevCommand": "npm run dev",
"beforeBuildCommand": "npm run build",
"withGlobalTauri": false
}
```
## `package`
<Properties anchorRoot="package" rows={[
{ property: "productName", optional: true, type: "string", description: `Application name. Defaults to the package name specified in Cargo.toml. The binary name is converted to snake-case on Linux.` },
{ property: "version", optional: true, type: "string", description: `Application version. Defaults to the version specified in Cargo.toml.` }
]}/>
## `tauri`
<Properties anchorRoot="tauri" rows={[
{
property: "cli", optional: true, type: "CliConfig",
child: <Properties anchorRoot="tauri.cli" rows={[
{ property: "args", optional: true, type: "CliArg[]", description: `List of args for the command.`, child: <Array type="CliArg" name="arg"><Properties anchorRoot="tauri.cli.args" rows={[
{ property: "short", optional: true, type: "string", description: `the short version of the argument, without the preceding hyphen (the "-" character).
<div class="alert alert--info" role="alert" style="margin-top: 10px;">
Any leading hyphen will be stripped, and only the first non hyphen character will be used as the short version.
</div>` },
{ property: "name", type: "string", description: `The unique argument name.` },
{ property: "description", optional: true, type: "string", description: `The argument description which will be shown on the help information. Typically, this is a short (one line) description of the arg.` },
{ property: "longDescription", optional: true, type: "string", description: `The argument long description which will be shown on the help information.
Typically, this a more detailed (multi-line) message that describes the argument` },
{ property: "takesValue", optional: true, type: "boolean", description: `Specifies that the argument takes a value at runtime.
<div class="alert alert--info" role="alert" style="margin-top: 10px;">
Values for arguments may be specified in any of the following methods:
<ul>
<li>Using a space such as <code>-o value</code> or <code>--option value</code></li>
<li>Using an equals and no space such as <code>-o=value</code> or <code>--option=value</code></li>
<li>Use a short and no space such as <code>-ovalue</code></li>
</ul>
</div>`
},
{ property: "index", type: "number", optional: true, description: `The positional argument index, starting at 1.
<div class="alert alert--info" role="alert" style="margin-top: 10px;">
The index refers to position according to other positional argument. It does not define position in the argument list as a whole.
When utilized with multiple=true, only the last positional argument may be defined as multiple (i.e. the one with the highest index).
</div>`
},
{ property: "multiple", optional: true, type: "boolean", description: `Specifies that the argument may appear more than once.
For flags, this results in the number of occurrences of the flag being recorded. For example <code>-ddd</code> or <code>-d -d -d</code> would count as three occurrences.
For options, there is a distinct difference in multiple occurrences vs multiple values. For example, <code>--opt val1 val2</code> is one occurrence, but two values. Whereas <code>--opt val1 --opt val2</code> is two occurrences.` },
{ property: "possibleValues", optional: true, type: "string[]", description: `Specifies a list of possible values for this argument. At runtime, the CLI verifies that only one of the specified values was used, or fails with an error message.` },
{ property: "minValues", optional: true, type: "number", description: `Specifies the minimum number of values for this argument.
For example, if you had a -f &lt;file&gt; argument where you wanted at least 2 "files" you would set <code>minValues: 2</code>, and this argument would be satisfied if the user provided, 2 or more values.` },
{ property: "maxValues", optional: true, type: "number", description: `Specifies the maximum number of values for this argument.
For example, if you had a -f &lt;file&gt; argument where you wanted up to 3 "files" you would set <code>max_values: 3</code>, and this argument would be satisfied if the user provided, 1, 2, or 3 values.` },
{ property: "required", optional: true, type: "boolean", description: `Sets whether or not the argument is required by default.
"required by default" means it is required, when no other conflicting rules have been evaluated
conflicting rules take precedence over being required.` },
{ property: "requiredUnless", optional: true, type: "string", description: `Sets an arg that overrides this arg's required setting.<br/>
i.e. this arg will be required unless this other argument is present.` },
{ property: "requiredUnlessAll", optional: true, type: "string[]", description: `Sets args that override this arg's required setting.<br/>
i.e. this arg will be required unless all these other arguments are present.` },
{ property: "requiredUnlessOne", optional: true, type: "string[]", description: `Sets args that override this arg's required setting.<br/>
i.e. this arg will be required unless at least one of these other arguments are present.` },
{ property: "conflictsWith", optional: true, type: "string", description: `Sets a conflicting argument by name
i.e. when using this argument, the following argument can't be present and vice versa.` },
{ property: "conflictsWithAll", optional: true, type: "string", description: `The same as <code>"conflictsWith"</code> but allows specifying multiple two-way conflicts per argument.` },
{ property: "requires", optional: true, type: "string", description: `Sets an argument by name that is required when this one is present.<br/>
i.e. when using this argument, the following argument must be present.` },
{ property: "requiresAll", optional: true, type: "string[]", description: `Sets multiple arguments by names that are required when this one is present.<br/>
i.e. when using this argument, the following arguments must be present.` },
{ property: "requiresIf", optional: true, type: "[string, string]", description: `Allows a conditional requirement with the signature <code>[arg: string, value: string]</code>.
<div class="alert alert--info" role="alert" style="margin-top: 10px;">
The requirement will only become valid if <code>"arg"</code>'s value equals <code>\${value}</code>.
</div>
` },
{ property: "requiredIf", optional: true, type: "[string, string]", description: `Allows specifying that an argument is required conditionally with the signature <code>[arg: string, value: string]</code>.
<div class="alert alert--info" role="alert" style="margin-top: 10px;">
The requirement will only become valid if the <code>"arg"</code>'s value equals <code>\${value}</code>.
</div>
` },
{ property: "requireEquals", optional: true, type: "boolean", description: `Requires that options use the <code>--option=val</code> syntax.<br/>
i.e. an equals between the option and associated value.` },
]} /></Array> },
{ property: "description", optional: true, type: "string", description: `Command description which will be shown on the help information.` },
{ property: "longDescription", optional: true, type: "string", description: `Command long description which will be shown on the help information.` },
{ property: "beforeHelp", optional: true, type: "string", description: `Adds additional help information to be displayed in addition to auto-generated help.<br/>
This information is displayed before the auto-generated help information.<br/>
This is often used for header information.` },
{ property: "afterHelp", optional: true, type: "string", description: `Adds additional help information to be displayed in addition to auto-generated help.<br/>
This information is displayed after the auto-generated help information.<br/>
This is often used to describe how to use the arguments, or caveats to be noted.` },
{ property: "subcommands", optional: true, type: "{ [name: string]: CliConfig }", description: `List of subcommands of this command.<br/>
Subcommands are effectively sub-apps, because they can contain their own arguments, subcommands, usage, etc.<br/>
They also function just like the app command, in that they get their own auto generated help and usage.` },
]} />
},
{
property: "bundle", type: "object",
child: <Properties anchorRoot="tauri.bundle" rows={[
{ property: "active", optional: true, type: "boolean", description: `Whether we should build your app with tauri-bundler or plain <code>cargo build</code>.` },
{ property: "targets", optional: true, type: "string | string[]", description: `An array of the bundles you want to generate; e.g. ["deb", "app", "msi", "appimage", "dmg"] or the string 'all' to make every supported bundle. By default we bundle everything your target supports (app/dmg on mac, deb/appimage on linux, msi on windows).` },
{ property: "identifier", type: "string", description: `A string that uniquely identifies your application, in reverse-DNS form (for example, "com.example.appname" or "io.github.username.project"). For OS X and iOS, this is used as the bundle's CFBundleIdentifier value; for Windows, this is hashed to create an application GUID.` },
{ property: "icon", optional: true, type: "string[]", description: `A list of (relative to src-tauri) icon paths to use for your application bundle.` },
{ property: "resources", optional: true, type: "string[]", description: `A list of files or directories which will be copied to the resources section of the bundle. Globs are supported.` },
{ property: "externalBin", optional: true, type: "string[]", description: `A list of—either absolute or relative—paths to binaries to embed with your application.
<div class="alert alert--info" role="alert" style="margin-top: 10px;">
Note that Tauri will look for system-specific binaries following the pattern "binary-name{-target-triple}{.system-extension}". <br/>
E.g. you typed "my-binary":
<ul>
<li>"my-binary-x86_64-pc-windows-msvc.exe" for Windows</li>
<li>"my-binary-x86_64-apple-darwin" for macOS</li>
<li>"my-binary-x86_64-unknown-linux-gnu" for Linux</li>
</ul>
so don't forget to provide binaries for <strong>all targeted platforms</strong>.
</div>` },
{ property: "copyright", optional: true, type: "string", description: `A copyright string associated with your application.` },
{ property: "category", optional: true, type: "string", description: `What kind of application this is.
Should be one among the following list: <br/>
Business, DeveloperTool, Education, Entertainment, Finance, Game, ActionGame, AdventureGame, ArcadeGame, BoardGame, CardGame, CasinoGame, DiceGame, EducationalGame, FamilyGame, KidsGame, MusicGame, PuzzleGame, RacingGame, RolePlayingGame, SimulationGame, SportsGame, StrategyGame, TriviaGame, WordGame, GraphicsAndDesign, HealthcareAndFitness, Lifestyle, Medical, Music, News, Photography, Productivity, Reference, SocialNetworking, Sports, Travel, Utility, Video, Weather.
` },
{ property: "shortDescription", optional: true, type: "string", description: `A short description of your application.` },
{ property: "longDescription", optional: true, type: "string", description: `A longer, multi-line description of the application.` },
{ property: "deb", optional: true, type: "object", child: <Properties anchorRoot="tauri.bundle.deb" rows={[
{ property: "depends", optional: true, type: "string[]", description: `The list of deb dependencies your application relies on.` },
{ property: "useBootstrapper", optional: true, type: "boolean", description: `Enable the <a href="/en/docs/guides/bundler/debian#bootstrapper">boostrapper script</a>.` },
{ property: "files", optional: true, type: "{ [path: string]: string }", description: `The files to include on the package. See <a href="/en/docs/guides/bundler/debian#custom-files">the debian guide</a>.` }]} />
},
{ property: "windows", optional: true, type: "object", child: <Properties anchorRoot="tauri.bundle.windows" rows={[
{ property: "digestAlgorithm", optional: true, type: "string", description: `Specifies the file digest algorithm to use for creating file signatures. Required for code signing. SHA-256 is recommended.` },
{ property: "certificateThumbprint", optional: true, type: "string[]", description: `Specifies the SHA1 hash of the signing certificate.` },
{ property: "timestampUrl", optional: true, type: "string[]", description: `Server to use during timestamping.` },
{ property: "wix", optional: true, type: "object", child: <Properties anchorRoot="tauri.bundle.windows.wix" rows={[
{ property: "language", optional: true, type: "string", description: `The installer language. See https://docs.microsoft.com/en-us/windows/win32/msi/localizing-the-error-and-actiontext-tables.` },
{ property: "template", optional: true, type: "string", description: `A custom .wxs template to use.` },
{ property: "fragmentPaths", optional: true, type: "string[]", description: `A list of paths to .wxs files with WiX fragments to use.` },
{ property: "componentGroupRefs", optional: true, type: "string[]", description: `The ComponentGroup element ids you want to reference from the fragments.` },
{ property: "componentRefs", optional: true, type: "string[]", description: `The Component element ids you want to reference from the fragments.` },
{ property: "featureGroupRefs", optional: true, type: "string[]", description: `The FeatureGroup element ids you want to reference from the fragments.` },
{ property: "featureRefs", optional: true, type: "string[]", description: `The Feature element ids you want to reference from the fragments.` },
{ property: "mergeRefs", optional: true, type: "string[]", description: `The Merge element ids you want to reference from the fragments.` },
{ property: "skipWebviewInstall", optional: true, type: "boolean", description: `Disables the Webview2 runtime installation after app install.` },
{ property: "license", optional: true, type: "string", description: `The path to the license file to render on the installer. Must be an RTF file, so if a different extension is provided, we convert it to the RTF format.` },
{ property: "bannerPath", optional: true, type: "string", description: `Path to a bitmap file to use as the installation user interface banner. This bitmap will appear at the top of all but the first page of the installer. The required dimensions are 493px × 58px.` },
{ property: "dialogImagePath", optional: true, type: "string", description: `Path to a bitmap file to use on the installation user interface dialogs. It is used on the welcome and completion dialogs. The required dimensions are 493px × 312px.` }]} />
}
]} />
},
{ property: "macOS", optional: true, type: "object", child: <Properties anchorRoot="tauri.bundle.macOS" rows={[
{ property: "frameworks", optional: true, type: "string[]", description: `A list of strings indicating any macOS X frameworks that need to be bundled with the application. If a name is used, ".framework" must be omitted and it will look for standard install locations. You may also use a path to a specific framework.` },
{ property: "minimumSystemVersion", optional: true, type: "string", description: `A version string indicating the minimum macOS X version that the bundled application supports.` },
{ property: "license", optional: true, type: "string", description: `The path to the license file to add to the DMG.` },
{ property: "useBootstrapper", optional: true, type: "boolean", description: `Enable the <a href="#bootstrapper">boostrapper script</a>.` },
{ property: "exceptionDomain", optional: true, type: "string", description: `Allows your application to communicate with the outside world.
<div class="alert alert--info" role="alert" style="margin-top: 10px;">
It should be a lowercase, without port and protocol domain name.
</div>
` },
{ property: "signingIdentity", optional: true, type: "string", description: `Identity to use for code signing.` },
{ property: "entitlements", optional: true, type: "string", description: `Path to the entitlements file.` },
]} /> },
]} />
},
{
property: "allowlist", type: "object",
child: <Properties anchorRoot="tauri.allowlist" rows={[
{ property: "all", type: "boolean", description: `Use this flag to enable all API features.` },
{
property: "fs", optional: true, type: "object", child: <Properties anchorRoot="tauri.allowlist.fs" rows={[
{ property: "all", type: "boolean", description: `Use this flag to enable all file system API features.` },
{ property: "readTextFile", optional: true, type: "boolean", description: `Read text file from local filesystem.` },
{ property: "readBinaryFile", optional: true, type: "boolean", description: `Read binary file from local filesystem.` },
{ property: "writeFile", optional: true, type: "boolean", description: `Write text file to local filesystem.` },
{ property: "writeBinaryFile", optional: true, type: "boolean", description: `Write binary file to local filesystem.` },
{ property: "readDir", optional: true, type: "boolean", description: `Read directory from local filesystem.` },
{ property: "copyFile", optional: true, type: "boolean", description: `Copy file from local filesystem.` },
{ property: "createDir", optional: true, type: "boolean", description: `Create directory from local filesystem.` },
{ property: "removeDir", optional: true, type: "boolean", description: `Remove directory from local filesystem.` },
{ property: "removeFile", optional: true, type: "boolean", description: `Remove file from local filesystem.` },
{ property: "renameFile", optional: true, type: "boolean", description: `Rename file from local filesystem.` },
]}/>
},
{
property: "window", optional: true, type: "object", child: <Properties anchorRoot="tauri.allowlist.window" rows={[
{ property: "all", type: "boolean", description: `Use this flag to enable all window API features.` },
{ property: "create", optional: true, type: "boolean", description: `Allows dynamic window creation.` },
]}/>
},
{
property: "shell", optional: true, type: "object", child: <Properties anchorRoot="tauri.allowlist.shell" rows={[
{ property: "all", type: "boolean", description: `Use this flag to enable all shell API features.` },
{ property: "execute", optional: true, type: "boolean", description: `Enable binary execution.` },
{ property: "open", optional: true, type: "boolean", description: `Open URL with the user's default application.` },
]}/>
},
{
property: "dialog", optional: true, type: "object", child: <Properties anchorRoot="tauri.allowlist.dialog" rows={[
{ property: "all", type: "boolean", description: `Use this flag to enable all dialog API features.` },
{ property: "open", optional: true, type: "boolean", description: `Open dialog window to pick files.` },
{ property: "save", optional: true, type: "boolean", description: `Open dialog window to pick where to save files.` },
]}/>
},
{
property: "http", optional: true, type: "object", child: <Properties anchorRoot="tauri.allowlist.http" rows={[
{ property: "all", type: "boolean", description: `Use this flag to enable all HTTP API features.` },
{ property: "request", optional: true, type: "boolean", description: `Allows making HTTP requests.` },
]}/>
},
{
property: "notification", optional: true, type: "object", child: <Properties anchorRoot="tauri.allowlist.notification" rows={[
{ property: "all", type: "boolean", description: `Use this flag to enable all notification API features.` },
]}/>
},
{
property: "globalShortcut", optional: true, type: "object", child: <Properties anchorRoot="tauri.allowlist.globalShortcut" rows={[
{ property: "all", type: "boolean", description: `Use this flag to enable all global shortcut API features.` },
]}/>
},
{
property: "os", optional: true, type: "object", child: <Properties anchorRoot="tauri.allowlist.os" rows={[
{ property: "all", type: "boolean", description: `Use this flag to enable all OS API features.` },
]}/>
},
{
property: "path", optional: true, type: "object", child: <Properties anchorRoot="tauri.allowlist.path" rows={[
{ property: "all", type: "boolean", description: `Use this flag to enable all path API features.` },
]}/>
},
]} />
},
{
property: "windows", type: "WindowConfig[]",
child: <Array type="WindowConfig" name="window">
<Properties anchorRoot="tauri.windows" rows={[
{ property: "label", type: "string", description: `Window id to reference on the codebase.` },
{ property: "url", type: "string", description: `URL to load on the webview.` },
{ property: "fileDropEnabled", type: "boolean", description: `Whether the file drop handler is enabled or not on the webview. Disabling it is required to use drag and drop on the frontend on Windows.` },
{ property: "center", type: "boolean", description: `Show window in the center of the screen.` },
{ property: "x", type: "number", description: `The horizontal position of the window's top left corner.` },
{ property: "y", type: "number", description: `The vertical position of the window's top left corner.` },
{ property: "width", optional: true, type: "number", description: `Initial window width.` },
{ property: "height", optional: true, type: "number", description: `Initial window height.` },
{ property: "minWidth", type: "number", description: `The minimum window width.` },
{ property: "minHeight", type: "number", description: `The minimum window height.` },
{ property: "maxWidth", type: "number", description: `The maximum window width.` },
{ property: "maxHeight", type: "number", description: `The maximum window height.` },
{ property: "resizable", optional: true, type: "boolean", description: `Whether the window is resizable or not..` },
{ property: "title", type: "string", description: `Window title.` },
{ property: "fullscreen", optional: true, type: "boolean", description: `Whether the window starts as fullscreen or not.` },
{ property: "focus", optional: true, type: "boolean", description: `Whether the window will be initially hidden or focused.` },
{ property: "transparent", optional: true, type: "boolean", description: `Whether the window is transparent or not.` },
{ property: "maximized", optional: true, type: "boolean", description: `Whether the window is maximized or not.` },
{ property: "visible", optional: true, type: "boolean", description: `Whether the window is visible or not.` },
{ property: "decorations", optional: true, type: "boolean", description: `Whether the window should have borders and bars.` },
{ property: "alwaysOnTop", optional: true, type: "boolean", description: `Whether the window should always be on top of other windows.` },
{ property: "skipTaskbar", optional: true, type: "boolean", description: `Whether or not the window icon should be added to the taskbar.` },
]}/>
</Array>
},
{
property: "security", type: "object",
child: <Properties anchorRoot="tauri.security" rows={[
{ property: "csp", optional: true, type: "string", description: `The Content Security Policy.
<div class="alert alert--warning" role="alert" style="margin-top: 10px;">
This is a really important part of the configuration since it helps you ensure your WebView is secured. See more <a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/CSP" target="_blank">on Mozilla</a>.
</div>` },
]} />
},
]} />
<!-- Dirty trick to have an anchor without make it appear in the table of contents -->
<div id="bootstrapper"></div>
<Alert title="bootstrapper script">
Instead of launching the app directly, we configure the bundled app to run a script that tries to expose the environment variables to the app; without that you'll have trouble using system CLI apps like Node.js.
</Alert>
```js title=Example
"tauri": {
"cli": {
"description": "Tauri communication example",
"longDescription": null,
"beforeHelp": null,
"afterHelp": null,
"args": [{
"short": "c",
"name": "config",
"takesValue": true,
"description": "Config path"
}, {
"short": "t",
"name": "theme",
"takesValue": true,
"description": "App theme",
"possibleValues": ["light", "dark", "system"]
}, {
"short": "v",
"name": "verbose",
"multipleOccurrences": true,
"description": "Verbosity level"
}],
"subcommands": {
"update": {
"description": "Updates the app",
"longDescription": null,
"beforeHelp": null,
"afterHelp": null,
"args": [{
"short": "b",
"name": "background",
"description": "Update in background"
}],
"subcommands": null
}
}
},
"bundle": {
"active": true,
"targets": ["deb"],
"identifier": "com.tauri.dev",
"icon": ["icons/32x32.png", "icons/128x128.png", "icons/128x128@2x.png", "icons/icon.icns", "icons/icon.ico"],
"resources": [],
"externalBin": [],
"copyright": "",
"category": "DeveloperTool",
"shortDescription": "",
"longDescription": "",
"deb": {
"depends": []
},
"macOS": {
"frameworks": [],
"minimumSystemVersion": "",
"exceptionDomain": ""
}
},
"allowlist": {
"all": true
},
"windows": [{
"title": "Tauri App",
"width": 800,
"height": 600,
"resizable": true,
"fullscreen": false
}],
"security": {
"csp": "default-src blob: data: filesystem: ws: wss: http: https: tauri: 'unsafe-eval' 'unsafe-inline' 'self'"
}
}
```

80
docs/development/ci-cd.md
View File

@ -1,80 +0,0 @@
---
id: ci-cd
title: CI/CD
---
## Continuous Integration
Github Actions has two triggers of which we make heavy use: `push` and `pull_request`. Every commit that made to the repo is a `push`. When you open a pull request from a branch (call it `great_feature`) to another branch (our working branch, `dev`), each commit to `great_feature` would possibly trigger both of these events. We can use a filter to focus on the events we care about though. In our workflows, we only PR (pull request) the `dev` and `master` branches. This means that if we filter to only the `dev` and `master` branches on commit, we will only run that workflow when we _merge_ a PR. A merged PR typically only occurs once a day or less so this will be a good fit for the longer running tests, e.g. the smoke tests in our case. Below is how that might look.
Unit tests:
```yml
# these run fast so we can have them run on any commit
name: unit tests
on:
pull_request:
push:
branches:
- dev
- master
```
Smoke tests:
```yml
# these run slower so we run only on merges to dev or master branch
name: smoke tests
on:
push:
branches:
- dev
- master
```
Tauri operates off the `dev` branch as default, and merges to `master` for release. With these Github Actions set up, we will run the unit tests on every commit to an open PR (see `pull_request`). When that PR is merged into `dev`, we will run both the unit tests and the smoke tests.
## Continuous Deployment
### Introduction to immutable checksum
It is not only possible, but trivial to modify release notes and artifacts after it has been published on Github. While there are very valid reasons for doing this, it is not exactly a totally trustworthy method - i.e. you have no guarantee that what you are reading is really reflective of the underlying truth or the tarballs. It is technically possible to change downloads over the wire or in the box or change checksums in targeted attacks. What we are seeking to accomplish is a best case scenario where:
1. Human error is reduced to a minimum, but humans are still integral in the actual release
2. Machine built assets, changelogs and attached security audits are verifiable with checksums that are published in an immutable, globally available store.
To this end we fashioned a workflow shown below. As it stands now, we have #3 through #6 implemented. We manually do #2 which then feeds into #3 and kicks off the rest of the automatic workflow.
1. a human pushes to dev through a pull request (can happen any number of times)
- pull request includes a changeset file describing the change and required version bump
2. a pull request is created (or updated) to include the change and version bump
- this pull request stays open and will be force pushed until it gets merged (and published)
- increase the version number based on changesets
- delete all changeset files
3. a codeowner merges the publish PR to dev (no direct push permissible for anyone)
- all tests (unit, e2e, smoke tests) are run on the PR
- failures prevent the publish so they must pass before merge
4. merge to dev triggers release sequence
- changes are squashed and a PR is opened against master
5. when PR to master is merged...
- vulnerability audit (crates and yarn) and output saved
- checksums and metadata and output saved
- packages are published on npm/cargo, tarball/zip created
- release is created for each package that had updates (if version isn't changed, build skips the publish steps)
- output from audit/checksums is piped into the release body
- tarball / zip attached to release
- async process to publish to IOTA tangle (feeless) via release tag [note: still have things to resolve here]
6. release is complete
- master has updated code and tagged
- GitHub release has tarballs, checksums, and changelog (may have multiple releases if more than one package published) [note: is part of step 2 and is not yet implemented]
### Next Steps
Next steps may include transferring and publishing the built assets to additional places:
1. Tauri's private verdaccio
2. IPFS
3. PureOS Gitlab
4. GitHub Packages
We can also do some interesting things like signing our releases, including a hash in the release and/or even publishing this information on a blockchain that it can be easily verified. Publishing on the blockchain is another avenue to increase the confidence that what is seen on GitHub matches what you have downloaded. The IOTA foundation created a Github Action which will publish a release to their blockchain. This has shown promise, but he gave a couple errors to tackle still.

5
docs/development/cross-platform.md
View File

@ -1,5 +0,0 @@
---
title: Cross-Platform Compilation
---
How to use GH Action for Building: a glance at Tauri Action.

60
docs/development/debugging.md
View File

@ -1,60 +0,0 @@
---
title: Debugging
---
import Alert from '@theme/Alert'
import Command from '@theme/Command'
With all the moving pieces in Tauri, you may run into a problem that requires debugging. There are a handful of locations where error details are printed, and Tauri includes some tools to make the debugging process easier.
## Rust Console
When you run a Tauri app in development mode you will have a Rust console available. This is in the terminal where you ran e.g. `tauri dev`. You can use the following code to print something to that console from within a Rust file:
```rust
println!("Message from Rust: {}", msg);
```
Sometimes you may have an error in your Rust code, and the Rust compiler can give you lots of information. If, for example, `tauri dev` crashes, you can rerun it like this on Linux and macOS:
```sh
RUST_DEBUG=1 tauri dev
```
or like this on MS Windows:
```sh
set RUST_DEBUG=1
tauri dev
```
This will give you a granular stack trace. Generally speaking, the Rust compiler will help you by
giving you detailed information about the issue, such as:
```
error[E0425]: cannot find value `sun` in this scope
--> src/main.rs:11:5
|
11 | sun += i.to_string().parse::<u64>().unwrap();
| ^^^ help: a local variable with a similar name exists: `sum`
error: aborting due to previous error
For more information about this error, try `rustc --explain E0425`.
```
## WebView JS Console
Right click in the WebView, and choose `Inspect Element`. This will open up a web-inspector similar to the Chrome or Firefox dev tools you are used to.
## Create a Debug Build
There are cases where you might need to inspect the JS console in the final bundle, so Tauri provides a simple command to create a debugging bundle:
<Command name="build --debug" />
Like the normal build and dev processes, the first time you run this it will take more time than subsequent runs. The final bundled app will be placed in `src-tauri/target/debug/bundle`. That app will ship with the development console enabled.
## Run Your App From the Terminal
You can also run a built app from the terminal, which will also give you the Rust compiler notes (in case of errors) or your `println` messages. Just find the file `src-tauri/target/(release|debug)/[app name]` and either double click it (but be warned, the terminal will close on errors) or just run it in directly in your console.

26
docs/development/development-cycle.md
View File

@ -1,26 +0,0 @@
---
title: Development Cycle
---
import Alert from '@theme/Alert'
import Command from '@theme/Command'
### 1. Start Your Devserver
Now that you have everything setup, you should start your application development server provided by your UI framework or bundler (assuming you're using one, of course).
<Alert title="Note">
Every framework has its own development tooling. It is outside of the scope of this document to treat them all or keep them up to date.
</Alert>
### 2. Start Tauri Development Window
<Command name="dev" />
The first time you run this command, it will take several minutes for the Rust package manager to download and build all the required packages. Since they are cached, subsequent builds will be much faster, as only your code will need rebuilding.
Once Rust has finished building, the webview will open and it should display your web app. You can make changes to your web app, and if your tooling enables it, the webview should update automatically just like a browser. When you make changes to your Rust files, they will be rebuilt automatically and your app will restart.
<Alert title="A note about Cargo.toml and Source Control" icon="info-alt">
In your project repository, you SHOULD commit the "src-tauri/Cargo.lock" along with the "src-tauri/Cargo.toml" to git because Cargo uses the lockfile to provide deterministic builds. As a result, it is recommended that all applications check in their Cargo.lock. You SHOULD NOT commit the "src-tauri/target" folder or any of its contents.
</Alert>

165
docs/development/integration.md
View File

@ -1,165 +0,0 @@
---
title: Integrate with Tauri
---
import Alert from '@theme/Alert'
import Command from '@theme/Command'
import Link from '@docusaurus/Link'
<Alert title="Please note" type="warning" icon="alert">
You must have completed all the steps required for setting up the development environment on your machine. If you haven't done this yet, please see the <a href="/docs/get-started/intro#setting-up-your-environment"> setup page for your operating system</a>.
</Alert>
There are two ways to integrate with Tauri depends on your need:
- [Start a new Tauri project](#1-start-a-new-tauri-project)
- Or [add Tauri to existing project](#1-add-tauri-to-existing-project)
### 1. Start a New Tauri Project
```bash
yarn create tauri-app
#OR
npx create-tauri-app
```
Just follow the instructions and choose the web frontend framework you prefer. `create-tauri-app` will create a template project depends on your inputs. You can go straight to [check `tauri info`](#3-check-tauri-info-to-make-sure-everything-is-set-up-properly) after this.
### 1. Add Tauri to Existing Project:
The Tauri CLI tool helps you build your project, so install it at first.
You can install Tauri CLI [using `Node.js`](#install-tauri-cli-package-as-a-dev-dependency) or [using `Rust`](#alternatively-install-tauri-cli-as-a-cargo-subcommand)
#### Install Tauri CLI package as a dev dependency:
```bash
cd project-folder
# Not required if you already have a package.json:
# yarn init
# OR
# npm init
yarn add -D @tauri-apps/cli
# OR
npm install -D @tauri-apps/cli
```
<Alert title="Note">
You can install Tauri as both a local and a global dependency, but we recommend installing it locally.
</Alert>
If you decide to use Tauri as a local package with npm (not yarn), you will have to define a custom script to your package.json:
```js title=package.json
{
// This content is just a sample
"scripts": {
"tauri": "tauri"
}
}
```
#### Alternatively, install Tauri CLI as a cargo subcommand:
This will install `tauri-cli` as a Cargo subcommand on the cargo binary folder (by default on `$HOME/.cargo/bin`):
```bash
cargo install tauri-cli --version ^1.0.0-beta
```
For more installation options, see [`cargo install`](https://doc.rust-lang.org/cargo/commands/cargo-install.html#description)
#### Install Tauri API Package as a Dependency (optional):
The `@tauri-apps/api` package is recommended for projects using ES modules or modern build tools such as Webpack or Vite. It is the most secure way to access the Tauri APIs.
```bash
yarn add @tauri-apps/api
# OR
npm install @tauri-apps/api
```
### 2. Initialize Tauri in Your App
<Command name="init" />
This command will place a new folder in your current working directory, `src-tauri`.
```sh
└── src-tauri
├── .gitignore
├── Cargo.toml
├── rustfmt.toml
├── tauri.conf.json
├── icons
│ ├── 128x128.png
│ ├── 128x128@2x.png
│ ├── 32x32.png
│ ├── Square107x107Logo.png
│ ├── Square142x142Logo.png
│ ├── Square150x150Logo.png
│ ├── Square284x284Logo.png
│ ├── Square30x30Logo.png
│ ├── Square310x310Logo.png
│ ├── Square44x44Logo.png
│ ├── Square71x71Logo.png
│ ├── Square89x89Logo.png
│ ├── StoreLogo.png
│ ├── icon.icns
│ ├── icon.ico
│ └── icon.png
└── src
├── build.rs
├── cmd.rs
└── main.rs
```
### 3. Check `tauri info` to Make Sure Everything Is Set up Properly:
<Command name="info" />
Which should return something like:
```
Operating System - Darwin(16.7.0) - darwin/x64
Node.js environment
Node.js - 12.16.3
@tauri-apps/cli - 1.0.0-beta.2
@tauri-apps/api - 1.0.0-beta.1
Global packages
npm - 6.14.4
yarn - 1.22.4
Rust environment
rustc - 1.52.1
cargo - 1.52.0
App directory structure
/node_modules
/src-tauri
/src
/public
App
tauri.rs - 1.0.0-beta.1
build-type - bundle
CSP - default-src blob: data: filesystem: ws: wss: http: https: tauri: 'unsafe-eval' 'unsafe-inline' 'self' img-src: 'self'
distDir - ../public
devPath - ../public
framework - Svelte
bundler - Rollup
```
This information can be very helpful when triaging problems.
### Patterns
We've also defined prebuilt configurations called "Patterns". They may help you to customize Tauri to fit your needs.
[See more about patterns](/docs/guides/patterns/about-patterns).
## Vue CLI Plugin Tauri
If you are using Vue CLI, it is recommended to use the official [CLI plugin](https://github.com/tauri-apps/vue-cli-plugin-tauri).

19
docs/development/intro.md
View File

@ -1,19 +0,0 @@
---
title: Introduction
---
This part of the documentation is dedicated to learning how to use Tauri.
Tauri provides a [CLI](/docs/api/cli), a Rust API, and a [JavaScript API](/docs/api/js/index) that you can use in your project. Because raw docs can be quite scary to newcomers (especially people who have never played with Rust before), we've created this "learn by example" section.
Here you will find guides and techniques to start a new project or add to your own project in order to fulfill your goals.
## Tauri Development Workflow
- [Integrate With Tauri](/docs/development/integration)
- [Development Cycle](/docs/development/development-cycle)
- [Debugging](/docs/development/debugging)
- [CI/CD](/docs/development/ci-cd)
- [Cross-Platform Compilation](/docs/development/cross-platform)
- [App Publishing](/docs/development/publishing)
- [Updating Packages](/docs/development/updating)

22
docs/development/publishing.md
View File

@ -1,22 +0,0 @@
---
title: App Publishing
---
import Alert from '@theme/Alert'
import Command from '@theme/Command'
### 1. Build Your Web App
Now that you are ready to package your project, you will need to run your framework's or bundler's build command (assuming you're using one, of course).
<Alert title="Note">
Every framework has its own publishing tooling. It is outside of the scope of this document to treat them all or keep them up to date.
</Alert>
### 2. Bundle your application with Tauri
<Command name="build" />
This command will embed your web assets into a single binary with your Rust code. The binary itself will be located in `src-tauri/target/release/[app name]`, and installers will be located in `src-tauri/target/release/bundle/`.
Like the `tauri dev` command, the first time you run this, it will take some time to collect the Rust crates and build everything - but on subsequent runs it will only need to rebuild your code, which is much quicker.

5
docs/development/signing-macos.md
View File

@ -1,5 +0,0 @@
---
title: Signing for macOS
---
Signing for macOS

42
docs/development/updating.md
View File

@ -1,42 +0,0 @@
---
title: Updating Packages
---
import Alert from '@theme/Alert'
<Alert title="Please note" type="warning" icon="alert">
Especially during the alpha and beta phases, you are expected to keep all Tauri dependencies and toolchains up to date. There is no support for any versions other than latest.
</Alert>
## Automatic updates
The Tauri JS CLI has a command to install and update all needed dependencies, just run `tauri deps install` or `tauri deps update`.
## Manual updates
### Update NPM Packages
If you are using the `tauri` package:
```bash
$ yarn upgrade @tauri-apps/cli @tauri-apps/api --latest
$ npm install @tauri-apps/cli@latest @tauri-apps/api@latest
```
You can also detect what the latest version of Tauri is on the command line, using:
- `npm outdated @tauri-apps/cli`
- `yarn outdated @tauri-apps/cli`
Alternatively, if you are using the `vue-cli-plugin-tauri` approach:
```bash
$ yarn upgrade vue-cli-plugin-tauri --latest
$ npm install vue-cli-plugin-tauri@latest
```
### Update Cargo Packages
Go to `src-tauri/Cargo.toml` and change `tauri` to
`tauri = { version = "%version%" }` where `%version%` is the version number shown above. (You can just use the `MAJOR.MINOR`) version, like `0.9`.
Then do the following:
```bash
$ cd src-tauri
$ cargo update -p tauri
```
You can also run `cargo outdated -r tauri` to get direct information about the core library's latest version.

18
docs/faq.md
View File

@ -1,18 +0,0 @@
---
title: Frequently Asked Questions
---
# error: could not find native static libraryWebView2LoaderStatic, perhaps an -L flag is missing?
The WebView2 crate build pipeline requires `NuGet` to have a `PackageSource` to install the `Microsoft.Web.WebView2` package. If you never used `NuGet` before, you might need to create a file named `NuGet.Config` on `%APPDATA%/NuGet` folder, with the following contents:
```
<?xml version="1.0" encoding="utf-8"?>
<configuration>
<packageSources>
<add key="nuget.org" value="https://api.nuget.org/v3/index.json" protocolVersion="3" />
</packageSources>
</configuration>
```
This configuration enables the default `NuGet` registry. After creating the file, you might need to remove the `src-tauri/target` folder and rebuild all crates.

47
docs/get-started/intro.md
View File

@ -1,47 +0,0 @@
---
title: Introduction
---
import OSList from '@theme/OSList'
Welcome to Tauri!
Tauri is a polyglot and generic system that is very composable and allows engineers to make a wide variety of applications. It is used for building applications for Desktop Computers using a combination of [Rust](https://www.rust-lang.org/) tools and HTML rendered in a Webview. Apps built with Tauri can ship with any number of pieces of an optional JS API / Rust API so that webviews can control the system via message passing.
Anything that can be displayed on a website, can be displayed in a Tauri webview app!
Developers are free to build the web front-end displayed in a Webview through Tauri with any web frameworks of their choice!
**Developers can even extend the default API** with their own functionality and bridge the Webview and Rust-based backend easily!
The Architecture is more fully described in [Architecture](/docs/about/architecture).
This guide will help you create your first Tauri app. It should only take about 10 minutes, although it could take longer if you have a slower internet connection.
If you find an error or something unclear, or would like to propose an improvement, you have several options:
1. Open an issue on our [Github Repo](https://github.com/tauri-apps/tauri-docs)
2. Visit our [Discord server](https://discord.gg/tauri) and raise your concern
3. Request to join the education working group on Discord to gain access to its discussion channel
## Steps
1. Install and configure system prerequisites
2. Create a web app with your frontend framework of choice
3. Use the Tauri CLI to setup Tauri in your app
4. Write native Rust code to add functionality or improve performance (totally optional)
5. Use `tauri dev` to develop your app with features like hot module reloading and webview devtools
6. Use `tauri build` to package your app into a tiny installer
### Setting up Your Environment
Before creating an app, you'll have to install and configure some developer tools. This guide assumes that you know what the command line is, how to install packages on your operating system, and generally know your way around the development side of computing.
Follow the platform-specific guides to get started:
<OSList content={{
linux: { title: 'Linux Setup', link: '/docs/get-started/setup-linux'},
macos: { title: 'macOS Setup', link: '/docs/get-started/setup-macos'},
windows: { title: 'Windows Setup', link: '/docs/get-started/setup-windows'}
}} />
After that, you'll be ready to [add Tauri to your project!](/docs/development/integration)

149
docs/get-started/setup-linux.md
View File

@ -1,149 +0,0 @@
---
title: Setup for Linux
---
import Alert from '@theme/Alert'
import Icon from '@theme/Icon'
import { Intro } from '@theme/SetupDocs'
import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';
<Intro />
## 1. System Dependencies&nbsp;<Icon title="alert" color="danger"/>
<Tabs
defaultValue="debian"
values={[
{label: 'Debian', value: 'debian'},
{label: 'Arch', value: 'arch'},
{label: 'Fedora', value: 'fedora'},
]}>
<TabItem value="debian">
```sh
$ sudo apt update && sudo apt install libwebkit2gtk-4.0-dev \
build-essential \
curl \
wget \
libssl-dev \
libgtk-3-dev \
libappindicator3-dev \
patchelf \
librsvg2-dev
```
</TabItem>
<TabItem value="arch">
```sh
$ sudo pacman -Syu && sudo pacman -S --needed \
webkit2gtk \
base-devel \
curl \
wget \
openssl \
appmenu-gtk-module \
gtk3 \
libappindicator-gtk3 \
patchelf \
librsvg \
libvips
```
</TabItem>
<TabItem value="fedora">
```sh
$ sudo dnf check-update && sudo dnf install webkit2gtk3-devel.x86_64 \
openssl-devel \
curl \
wget \
libappindicator-gtk3 \
patchelf \
librsvg2-devel \
&& sudo dnf group install "C Development Tools and Libraries"
```
</TabItem>
</Tabs>
### Optional dependencies:
- `libappindicator`: needed to use the system tray feature.
- `patchelf` and `librsvg`: needed to bundle `AppImage`.
## 2. Node.js Runtime and Package Manager&nbsp;<Icon title="control-skip-forward" color="warning"/>
### Node.js (npm included)
We recommend using nvm to manage your Node.js runtime. It allows you to easily switch versions and update Node.js.
```sh
$ curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.35.2/install.sh | bash
```
<Alert title="Note">
We have audited this bash script, and it does what it says it is supposed to do. Nevertheless, before blindly curl-bashing a script, it is always wise to look at it first. Here is the file as a mere <a href="https://raw.githubusercontent.com/nvm-sh/nvm/v0.35.2/install.sh" target="_blank">download link</a>.
</Alert>
Once nvm is installed, close and reopen your terminal, then install the latest version of Node.js and npm:
```sh
$ nvm install node --latest-npm
$ nvm use node
```
If you have any problems with nvm, please consult their <a href="https://github.com/nvm-sh/nvm">project readme</a>.
### Optional Node.js Package Manager
You may want to use an alternative to npm:
- <a href="https://yarnpkg.com/get-started" target="_blank">Yarn</a>, is preferred by Tauri's team
- <a href="https://pnpm.js.org/en/installation" target="_blank">pnpm</a>
## 3. Rustc and Cargo Package Manager&nbsp;<Icon title="control-skip-forward" color="warning"/>
The following command will install <a href="https://rustup.rs/" target="_blank">rustup</a>, the official installer for <a href="https://www.rust-lang.org/" target="_blank">Rust</a>.
```bash
$ curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
```
<Alert title="Note">
We have audited this bash script, and it does what it says it is supposed to do. Nevertheless, before blindly curl-bashing a script, it is always wise to look at it first. Here is the file as a mere <a href="https://sh.rustup.rs" target="_blank">download link</a>.
</Alert>
To make sure that Rust has been installed successfully, run the following command:
```sh
$ rustc --version
latest update on 2019-12-19, rust version 1.40.0
```
You may need to restart your terminal if the command does not work.
## 4. For Windows Subsystem for Linux (WSL) Users&nbsp;<Icon title="info-alt" color="info"/>
In order to run a graphical application with WSL, you need to download **one** of these X servers: Xming, Cygwin X, and vcXsrv.
Since vcXsrv has been used internally, it's the one we recommend to install.
### WSL Version 1
Open the X server and then run `export DISPLAY=:0` in the terminal. You should now be able to run any graphical application via the terminal.
### WSL Version 2
You'll need to run a command that is slightly more complex than WSL 1: `export DISPLAY=$(cat /etc/resolv.conf | grep nameserver | awk '{print $2}'):0` and you need to add `-ac` to the X server as an argument. Note: if for some reason this command doesn't work you can use an alternative command such as: `export DISPLAY=$(cat /etc/resolv.conf | grep nameserver | sed 's/.* //g'):0` or you can manually find the Address using `cat /etc/resolve.conf | grep nameserver`.
<Alert type="info" title="Note">
Don't forget that you'll have to use the "export" command anytime you want to use a graphical application, for each newly opened terminal.
You can download some examples to try with `sudo apt-get install x11-apps`. xeyes is always a good one. It can be handy when troubleshooting WSL issues.
</Alert>
## Continue
Now that you have set up the Linux-specific dependencies for Tauri, learn how to [add Tauri to your project](/docs/development/integration).

79
docs/get-started/setup-macos.md
View File

@ -1,79 +0,0 @@
---
title: Setup for macOS
---
import Alert from '@theme/Alert'
import { Intro } from '@theme/SetupDocs'
import Icon from '@theme/Icon'
<Intro />
## 1. System Dependencies&nbsp;<Icon title="alert" color="danger"/>
You will need to have <a href="https://brew.sh/" target="_blank">Homebrew</a> installed to run the following command.
```sh
$ brew install gcc
```
You will also need to make sure `xcode` is installed.
```sh
$ xcode-select --install
```
## 2. Node.js Runtime and Package Manager&nbsp;<Icon title="control-skip-forward" color="warning"/>
### Node.js (npm included)
We recommend using nvm to manage your Node.js runtime. It allows you to easily switch versions and update Node.js.
```sh
$ curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.35.2/install.sh | bash
```
<Alert title="Note">
We have audited this bash script, and it does what it says it is supposed to do. Nevertheless, before blindly curl-bashing a script, it is always wise to look at it first. Here is the file as a mere <a href="https://raw.githubusercontent.com/nvm-sh/nvm/v0.35.2/install.sh" target="_blank">download link</a>.
</Alert>
Once nvm is installed, close and reopen your terminal, then install the latest version of Node.js and npm:
```sh
$ nvm install node --latest-npm
$ nvm use node
```
If you have any problems with nvm, please consult their <a href="https://github.com/nvm-sh/nvm">project readme</a>.
### Optional Node.js Package Manager
You may want to use an alternative to npm:
- <a href="https://yarnpkg.com/get-started" target="_blank">Yarn</a>, is preferred by Tauri's team
- <a href="https://pnpm.js.org/en/installation" target="_blank">pnpm</a>
## 3. Rustc and Cargo Package Manager&nbsp;<Icon title="control-skip-forward" color="warning"/>
The following command will install <a href="https://rustup.rs/" target="_blank">rustup</a>, the official installer for <a href="https://www.rust-lang.org/" target="_blank">Rust</a>.
```
$ curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
```
<Alert title="Note">
We have audited this bash script, and it does what it says it is supposed to do. Nevertheless, before blindly curl-bashing a script, it is always wise to look at it first. Here is the file as a mere <a href="https://sh.rustup.rs" target="_blank">download link</a>.
</Alert>
To make sure that Rust has been installed successfully, run the following command:
```sh
$ rustc --version
latest update on 2019-12-19, rust version 1.40.0
```
You may need to restart your terminal if the command does not work.
## Continue
Now that you have set up the macOS-specific dependencies for Tauri, learn how to [add Tauri to your project](/docs/development/integration).

75
docs/get-started/setup-windows.md
View File

@ -1,75 +0,0 @@
---
title: Setup for Windows
---
import Alert from '@theme/Alert'
import Icon from '@theme/Icon'
import { Intro } from '@theme/SetupDocs'
<Alert title="Note">
For those using the Windows Subsystem for Linux (WSL) please refer to our [Linux specific instructions](/docs/get-started/setup-linux) instead.
</Alert>
<Intro />
## 1. System Dependencies&nbsp;<Icon title="alert" color="danger"/>
You'll need to install Microsoft Visual Studio C++ build tools. <a href="https://visualstudio.microsoft.com/visual-cpp-build-tools/" target="_blank">Download the installer here</a>, and then run it. When it asks you what packages you would like to install, select C++ Build Tools and make sure the Windows SDK is selected.
<Alert title="Note">
This is a big download (over 1GB) and takes the most time, so go grab a coffee.
</Alert>
<Alert type="warning">
You may need to uninstall the 2017 version of the build tools if you have them. There are reports of Tauri not working with both the 2017 and 2019 versions installed.
</Alert>
## 2. Node.js Runtime and Package Manager&nbsp;<Icon title="control-skip-forward" color="warning"/>
### Node.js (npm included)
We recommend using <a href="https://github.com/coreybutler/nvm-windows#installation--upgrades" target="_blank">nvm-windows</a> to manage your Node.js runtime. It allows you to easily switch versions and update Node.js.
Then run the following from an Administrative PowerShell and press Y when prompted:
```powershell
# BE SURE YOU ARE IN AN ADMINISTRATIVE PowerShell!
nvm install latest
nvm use {{latest}} # Replace with your latest downloaded version
```
This will install the most recent version of Node.js with npm.
### Optional Node.js Package Manager
You may want to use an alternative to npm:
- <a href="https://yarnpkg.com/get-started" target="_blank">Yarn</a>, is preferred by Tauri's team
- <a href="https://pnpm.js.org/en/installation" target="_blank">pnpm</a>
## 3. Rustc and Cargo Package Manager&nbsp;<Icon title="control-skip-forward" color="warning"/>
Now you will need to install <a href="https://www.rust-lang.org/" target="_blank">Rust</a>. The easiest way to do this is to use <a href="https://rustup.rs/" target="_blank">rustup</a>, the official installer.
- <a href="https://win.rustup.rs/x86_64" target="_blank">64-bit download link</a>
- <a href="https://win.rustup.rs/i686" target="_blank">32-bit download link</a>
Download and install the proper variant for your computer's architecture.
## 4. Install WebView2
<Alert title="Note">
WebView2 is pre-installed in Windows 11.
</Alert>
Finally, you will need to install WebView2. The best way to do this is to download and run the Evergreen Bootstrapper from [this page](https://developer.microsoft.com/en-us/microsoft-edge/webview2/#download-section).
<Alert type="Note">
If you have problems of any kind after following these instructions, we recommend that you reboot your computer before developing a Tauri project to ensure that everything works as expected.
</Alert>
## Continue
Now that you have set up the Windows-specific dependencies for Tauri, learn how to [add Tauri to your project](/docs/development/integration).

107
docs/guides/bundler/anti-bloat.md
View File

@ -1,107 +0,0 @@
---
title: Anti Bloat
---
import Alert from '@theme/Alert'
The following links have tutorials on reducing the size of your installers:
- https://github.com/RazrFalcon/cargo-bloat
- https://lifthrasiir.github.io/rustlog/why-is-a-rust-executable-large.html
- https://doc.rust-lang.org/cargo/reference/manifest.html#the-profile-sections
### Rust Compression Features
Add this to your `src-tauri/Cargo.toml`
[profile.release]
panic = "abort"
codegen-units = 1
lto = true
incremental = false
opt-level = "s"
<Alert title="Note">
There is also `opt-level = "z"` available to try to reduce the resulting binary size. `"s"` and `"z"` can sometimes be smaller than the other, so test it with your own application!
We've seen smaller binary sizes from `"s"` for Tauri example applications, but real world applications can always differ.
</Alert>
#### Unstable Rust Compression Features
<Alert type="warning" title="Warning" icon="alert">
The following suggestions are all unstable features and require a nightly toolchain. See the <a href="https://doc.rust-lang.org/cargo/reference/unstable.html#unstable-features">Unstable Features</a> documentation for more information of what this involves.
</Alert>
The following methods involve using unstable compiler features and require having a rust nightly toolchain installed. If you don't have the nightly toolchain + `rust-src` nightly component added, try the following:
$ rustup toolchain install nightly
$ rustup component add rust-src --toolchain nightly
The Rust Standard Library comes precompiled. You can instead apply the optimization options used for the rest of your binary + dependencies to the std with an unstable flag. This flag requires specifying your target, so know the target triple that you are targeting.
$ cargo +nightly build --release -Z build-std --target x86_64-unknown-linux-gnu
If you are using `panic = "abort"` in your release profile optimizations, then you need to make sure the `panic_abort` crate is compiled with std. Additionally, an extra std feature can be used to further reduce the binary size. The following applies both:
$ cargo +nightly build --release -Z build-std=std,panic_abort -Z build-std-features=panic_immediate_abort --target x86_64-unknown-linux-gnu
See the unstable documentation for more details about [`-Z build-std`](https://doc.rust-lang.org/cargo/reference/unstable.html#build-std) and [`-Z build-std-features`](https://doc.rust-lang.org/cargo/reference/unstable.html#build-std-features).
### Stripping
Binary size can easily be reduced by stripping out debugging information from binaries that ship to end users. This is not good for debuggable builds, but means good binary size savings for end user binaries. The easiest way is to use the famous `strip` utility to remove this debugging information.
$ strip target/release/my_application
See your local `strip` manpage for more information and flags that can be used to specify what information gets stripped out from the binary.
### Allowlist config
You can also reduce the application size with the `allowlist` config, and only enabling what you need. Sometimes this is useful with Tauri's [Bridge-Pattern](/docs/guides/patterns/bridge) or others, depending on needs.
For example in `tauri.conf.json` file:
```json
{
"tauri": {
"allowlist": {
"all": false,
"fs": {
"writeFile": true,
"writeBinaryFile": true
},
"shell": {
"execute": true
},
"dialog": {
"save": true
}
}
}
}
```
### UPX
UPX, **Ultimate Packer for eXecutables**, is a dinosaur amongst the binary packers. This 23-year old, well-maintained piece of kit is GPL-v2 licensed with a pretty liberal usage declaration. Our understanding of the licensing is that you can use it for any purposes (commercial or otherwise) without needing to change your license unless you modify the source code of UPX.
Basically it compresses the binary and decompresses it at runtime. It should work for pretty much any binary type out there. Read more: https://github.com/upx/upx
<Alert type="warning" title="Warning" icon="alert">
You should know that this technique might flag your binary as a virus on Windows and macOS - so use at your own discretion, and as always validate with [Frida](https://frida.re/docs/home/) and do real distribution testing!
</Alert>
#### Usage on macOS
$ brew install upx
$ yarn tauri build
$ upx --ultra-brute src-tauri/target/release/bundle/macos/app.app/Contents/macOS/app
Ultimate Packer for eXecutables
Copyright (C) 1996 - 2018
UPX 3.95 Markus Oberhumer, Laszlo Molnar & John Reiser Aug 26th 2018
File size Ratio Format Name
-------------------- ------ ----------- -----------
963140 -> 274448 28.50% macho/amd64 app

34
docs/guides/bundler/debian.md
View File

@ -1,34 +0,0 @@
---
title: Debian packages
---
import Alert from '@theme/Alert'
Tauri allows your app to be packaged as a `.deb` (Debian package) file.
# Bootstrapper
Instead of launching the app directly, you can configure the bundled app to run a script that tries to expose the environment variables to the app; without that you'll have trouble using system programs because the `PATH` environment variable isn't correct. Enable it with the <a href="/docs/api/config#tauri.bundle.deb.useBootstrapper">`useBootstrapper`</a> config.
# Custom files
To include custom files to the debian package, you can configure a mapping on `tauri.conf.json > tauri > bundle > deb > files` as follows:
```json
{
"tauri": {
"bundle": {
"deb": {
"files": {
"/usr/lib/README.md": "../README.md", // copies the README.md file to /usr/lib/README.md
"usr/lib/assets": "../public/" // copies the entire public directory to /usr/lib/assets
}
}
}
}
}
```
<Alert title="Note" icon="info-alt">
Each `files` object key is the path on the debian package, and the value is a path to a file or directory relative to the `tauri.conf.json` file.
</Alert>

11
docs/guides/bundler/introduction.md
View File

@ -1,11 +0,0 @@
---
title: Introduction
---
The Tauri Bundler is a Rust harness for compiling your binary, packaging assets, and preparing a final bundle.
It will detect your operating system and build a bundle accordingly. It currently supports:
- Linux: .deb, .appimage
- macOS: .app, .dmg
- Windows: .exe, .msi

102
docs/guides/bundler/sidecar.md
View File

@ -1,102 +0,0 @@
---
title: Sidecar (Embedding External Binaries)
sidebar_label: Sidecar
---
import Alert from '@theme/Alert'
You may need to embed depending binaries in order to make your application work or to prevent users having to install additional dependencies (e.g. Node.js, Python, etc).
To bundle the binaries of your choice, you can add the `externalBin` property to the `tauri > bundle` object in your `tauri.conf.json`.
See more about tauri.conf.json configuration <a href="/docs/api/config#tauri.bundle">here</a>.
`externalBin` expects a list of strings targeting binaries either with absolute or relative paths.
Here is a sample to illustrate the configuration, this is not a complete `tauri.conf.json` file:
```json
{
"tauri": {
"bundle": {
"externalBin": ["/absolute/path/to/app", "relative/path/to/binary", "bin/python"]
}
}
}
```
A binary with the same name and a `-$TARGET_TRIPLE` suffix must exist on the specified path. For instance, `"externalBin": ["bin/python"]` requires a `src-tauri/bin/python-x86_64-unknown-linux-gnu` executable on Linux. You can find the current platform's target triple running the following command:
```bash
rustc -Vv | grep host | cut -f2 -d' '
```
Here's a Node.js script to append the target triple to a binary:
```javascript
const execa = require('execa')
const fs = require('fs')
let extension = ''
if (process.platform === 'win32') {
extension = '.exe'
}
async function main() {
const rustInfo = (await execa('rustc', ['-vV'])).stdout
const targetTriple = /host: (\S+)/g.exec(rustInfo)[1]
if (!targetTriple) {
console.error('Failed to determine platform target triple')
}
fs.renameSync(
`src-tauri/binaries/app${extension}`,
`src-tauri/binaries/app-${targetTriple}${extension}`
)
}
main().catch((e) => {
throw e
})
```
## Running the sidecar binary on JavaScript
On the JavaScript code, import the `Command` class on the `shell` module and use the `sidecar` static method:
```javascript
import { Command } from '@tauri-apps/api/shell'
// alternatively, use `window.__TAURI__.shell.Command`
// `my-sidecar` is the value specified on `tauri.conf.json > tauri > bundle > externalBin`
const command = Command.sidecar('my-sidecar')
const output = await command.execute()
```
## Running the sidecar binary on Rust
On the Rust code, import the `Command` struct from the `tauri::api::process` module:
```rust
let (mut rx, mut child) = Command::new_sidecar("my-sidecar")
.expect("failed to create `my-sidecar` binary command")
.spawn()
.expect("Failed to spawn sidecar");
tauri::async_runtime::spawn(async move {
// read events such as stdout
while let Some(event) = rx.recv().await {
if let CommandEvent::Stdout(line) = event {
window
.emit("message", Some(format!("'{}'", line)))
.expect("failed to emit event");
// write to stdin
child.write("message from Rust\n".as_bytes()).unwrap();
}
}
});
```
## Using Node.js on a sidecar
The Tauri [sidecar example](https://github.com/tauri-apps/tauri/tree/dev/examples/sidecar) demonstrates how to use the sidecar API to run a Node.js application on Tauri.
It compiles the Node.js code using [pkg](https://github.com/vercel/pkg) and uses the scripts above to run it.

104
docs/guides/bundler/sign-macos.md
View File

@ -1,104 +0,0 @@
---
title: macOS - Code signing guide using Github Actions
sidebar_label: macOS - Code signing
---
import Alert from '@theme/Alert'
## Intro
Tauri has a smooth code-signing & notarization functionality built directly into the bundler and configured via the `tauri.conf.json`
This guide will give a brief overview of how to sign an application, and how to get the app notarized with Apple. All in a GitHub action.
## Prerequisits
- OSX - This will be needed to create/export the certificate.
- [Apple Developer Program](https://developer.apple.com/programs/) subscription
- [Developer ID Application](https://developer.apple.com/developer-id/) certificate
- see [this](https://localazy.com/blog/how-to-automatically-sign-macos-apps-using-github-actions#reference) guide for additional help
- Working Tauri application, being built and published via GitHub Actions, as shown in [tauri-action](https://github.com/tauri-apps/tauri-action)
<Alert title="Note" icon="info-alt">
If you are not utilizing GitHub Actions to perform builds of OSX DMGs, you will need to ensure the environment variable `CI=true` exists. For more information refer to [Issue #592](https://github.com/tauri-apps/tauri/issues/592).
</Alert>
## GitHub Secrets
We will need to add a few GitHub secrets for the proper configuration of the GitHub Action. These can be named however you would like, but we must assign them to the correct Tauri variables, so keep them as relevant as possible.
- You can view [this](https://docs.github.com/en/actions/reference/encrypted-secrets) guide for how to add GitHub secrets.
The secrets I used are as follows
| GitHub Secrets | Value for Variable |
| :---: | :---: |
|APPLE_CERTIFICATE| Base64 encoded version of your .p12 certificate. You can find a guide [here](https://localazy.com/blog/how-to-automatically-sign-macos-apps-using-github-actions#reference)|
|APPLE_CERTIFICATE_PASSWORD|Certificate password used on creation of certificate|
|APPLE_IDENTITY_ID|"Developer ID Application: Your Company, Inc (XXXXXXXXX)" shown in your keychain. you can also use `security find-identity -v -p codesigning` on OSX to find this identity |
|APPLE_ID|this is the email used to request the certificate|
APPLE_PASSWORD|This is an app-specific password, that must also be created by the same account used to request the certificate. Guide [here](https://support.apple.com/en-ca/HT204397)|
Once we have established the GitHub Secrets we will need to make some modifications to our GitHub publish action in `.github/workflows/main.yml`
---
### Workflow Modifications
All we will have to do from here is assign the GitHub secrets to the proper environment variables.
```
ENABLE_CODE_SIGNING: ${{ secrets.APPLE_CERTIFICATE }}
APPLE_CERTIFICATE: ${{ secrets.APPLE_CERTIFICATE }}
APPLE_CERTIFICATE_PASSWORD: ${{ secrets.APPLE_CERTIFICATE_PASSWORD }}
APPLE_SIGNING_IDENTITY: ${{ secrets.APPLE_IDENTITY_ID }}
APPLE_ID: ${{ secrets.APPLE_ID }}
APPLE_PASSWORD: ${{ secrets.APPLE_PASSWORD }}
```
If you are using the tauri-action publish template, then your result should look similar the the `env:` portion below.
```
name: "publish"
on:
push:
branches:
- release
jobs:
publish-tauri:
strategy:
fail-fast: false
matrix:
platform: [macos-latest, ubuntu-latest, windows-latest]
runs-on: ${{ matrix.platform }}
steps:
- uses: actions/checkout@v2
- name: setup node
uses: actions/setup-node@v2
with:
node-version: 12
- name: install Rust stable
uses: actions-rs/toolchain@v1
with:
toolchain: stable
- name: install webkit2gtk (ubuntu only)
if: matrix.platform == 'ubuntu-latest'
run: |
sudo apt-get update
sudo apt-get install -y webkit2gtk-4.0
- name: install app dependencies and build it
run: yarn && yarn build
- uses: tauri-apps/tauri-action@v0
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
ENABLE_CODE_SIGNING: ${{ secrets.APPLE_CERTIFICATE }}
APPLE_CERTIFICATE: ${{ secrets.APPLE_CERTIFICATE }}
APPLE_CERTIFICATE_PASSWORD: ${{ secrets.APPLE_CERTIFICATE_PASSWORD }}
APPLE_SIGNING_IDENTITY: ${{ secrets.APPLE_IDENTITY_ID }}
APPLE_ID: ${{ secrets.APPLE_ID }}
APPLE_PASSWORD: ${{ secrets.APPLE_PASSWORD }}
with:
tagName: app-v__VERSION__ # the action automatically replaces \_\_VERSION\_\_ with the app version
releaseName: "App v__VERSION__"
releaseBody: "See the assets to download this version and install."
releaseDraft: true
prerelease: false
```

81
docs/guides/bundler/sign-windows.md
View File

@ -1,81 +0,0 @@
---
title: Windows - Code signing guide locally & with Github Actions
sidebar_label: Windows - Code signing
---
import Alert from '@theme/Alert'
# Intro
Code-signing will add a level of authenticity to your application, while it is not required it can often improve the user experience for your users.
# Prerequisites
- Windows - you can likely use other platforms, but this tutorial is using Powershell native features.
- Code signing certificate - you can aqquire one of these on services such as Digicert.com, Comodo.com, & Godaddy.com. In this guide we are using Comodo.com
- A working tauri application
# Getting Started
There are a few things we will have to do to get our windows installation prepared for code signing. This includes converting our certificate to a speific format, installing this certificate, & then decoding required information from certificate that is required by tauri.
## A. Convert your `.cer` to `.pfx`
1. You will need the following:
- certificate file (mine is `cert.cer`)
- private key file (mine is `private-key.key`)
2. Open up a command prompt and change to your current directory using `cd Documents/Certs`
3. Convert your `.cer` to a `.pfx` using `openssl pkcs12 -export -in cert.cer -inkey private-key.key -out certificate.pfx`
4. You will be prompted to enter an export password **DON'T FORGET IT!**
## B. Import your `.pfx` file into the keystore.
We will now need to import our `.pfx` file.
1. Assign your export password to a variable using `$WINDOWS_PFX_PASSWORD = 'MYPASSWORD'`
2. Now Import the certificate using `Import-PfxCertificate -FilePath Certs/certificate.pfx -CertStoreLocation Cert:\LocalMachine\My -Password (ConvertTo-SecureString -String $env:WINDOWS_PFX_PASSWORD -Force -AsPlainText)`
## C. Prepare Variables
1. We will need the SHA-1 thumbprint of the certificate, you can get this using `openssl pkcs12 -info -in certificate.pfx` and look under for following
```
Bag Attributes
localKeyID: A1 B1 A2 B2 A3 B3 A4 B4 A5 B5 A6 B6 A7 B7 A8 B8 A9 B9 A0 B0
```
2. You will capture the `localKeyID` but with no spaces, in this example it would be `A1B1A2B2A3B3A4B4A5B5A6B6A7B7A8B8A9B9A0B0`. This is our `certificateThumbprint`.
3. We will need the SHA digest algorythm used for your certificate (Hint: this is likely `sha256`
4. We will also need a timestamp url, this is a time server used to verify the time of the certificate signing. Im using `http://timestamp.comodoca.com` but whoever you got your certificate from likely has one aswell.
# Prepare `tauri.conf.json` file
1. Now that we have our `certificateThumbprint`, `digestAlgorithm`, & `timestampUrl` we will open up the `tauri.conf.json`.
2. In the `tauri.conf.json` you will look for the `tauri` -> `bundle` -> `windows` section. You will see there are three variable for the information we have captured. Fill it out like below.
```
"windows": {
"certificateThumbprint": "A1B1A2B2A3B3A4B4A5B5A6B6A7B7A8B8A9B9A0B0",
"digestAlgorithm": "sha256",
"timestampUrl": "http://timestamp.comodoca.com"
}
```
3. Save, and run `yarn | yarn build`
4. In the console output you will see the following output.
```
info: signing app
info: running signtool "C:\\Program Files (x86)\\Windows Kits\\10\\bin\\10.0.19041.0\\x64\\signtool.exe"
info: "Done Adding Additional Store\r\nSuccessfully signed: APPLICATION FILE PATH HERE
```
which shows you have successfully signed the `.exe`.
And thats it! You have successfully signed your .exe file.

162
docs/guides/cli.md
View File

@ -1,162 +0,0 @@
---
title: Make your own CLI
---
import Alert from '@theme/Alert'
Tauri enables your app to have a CLI through <a href="https://github.com/clap-rs/clap" target="_blank">clap</a>, a robust command line argument parser. With a simple CLI definition in your `tauri.conf.json` file, you can define your interface and read its argument matches map on JavaScript and/or Rust.
## Base Configuration
Under `tauri.conf.json`, you have the following structure to configure the interface:
```js title=src-tauri/tauri.conf.json
{
"tauri": {
"cli": {
"description": "", // command description that's shown on help
"longDescription": "", // command long description that's shown on help
"beforeHelp": "", // content to show before the help text
"afterHelp": "", // content to show after the help text
"args": [], // list of arguments of the command, we'll explain it later
"subcommands": {
"subcommand-name": {
// configures a subcommand that is accessible
// with `$ ./app subcommand-name --arg1 --arg2 --etc`
// configuration as above, with "description", "args", etc.
}
}
}
}
}
```
<Alert title="Note">
All JSON configurations here are just samples, many other fields have been omitted for the sake of clarity.
</Alert>
## Adding Arguments
The `args` array represents the list of arguments accepted by its command or subcommand. You can find more details about the way to configure them <a href="/docs/api/config#tauri">here</a>.
### Positional Arguments
A positional argument is identified by its position in the list of arguments. With the following configuration:
```json title=src-tauri/tauri.conf.json:tauri.cli
{
"args": [
{
"name": "source",
"index": 1,
"takesValue": true
},
{
"name": "destination",
"index": 2,
"takesValue": true
}
]
}
```
Users can run your app as `$ ./app tauri.txt dest.txt` and the arg matches map will define `source` as `"tauri.txt"` and `destination` as `"dest.txt"`.
### Named Arguments
A named argument is a (key, value) pair where the key identifies the value. With the following configuration:
```json title=src-tauri/tauri.conf.json:tauri.cli
{
"args": [
{
"name": "type",
"short": "t",
"takesValue": true,
"multiple": true,
"possibleValues": ["foo", "bar"]
}
]
}
```
Users can run your app as `$ ./app --type foo bar`, `$ ./app -t foo -t bar` or `$ ./app --type=foo,bar` and the arg matches map will define `type` as `["foo", "bar"]`.
### Flag Arguments
A flag argument is a standalone key whose presence or absence provides information to your application. With the following configuration:
```js title=src-tauri/tauri.conf.json:tauri.cli
{
"args": [
"name": "verbose",
"short": "v",
"multipleOccurrences": true
]
}
```
Users can run your app as `$ ./app -v -v -v`, `$ ./app --verbose --verbose --verbose` or `$ ./app -vvv` and the arg matches map will define `verbose` as `true`, with `occurrences = 3`.
## Subcommands
Some CLI applications has additional interfaces as subcommands. For instance, the `git` CLI has `git branch`, `git commit` and `git push`. You can define additional nested interfaces with the `subcommands` array:
```js title=src-tauri/tauri.conf.json:tauri
{
"cli": {
...
"subcommands": {
"branch": {
"args": []
},
"push": {
"args": []
}
}
}
}
```
Its configuration is the same as the root application configuration, with the `description`, `longDescription`, `args`, etc.
## Reading the matches
### Rust
```rust
use tauri::api::cli::get_matches;
fn main() {
let context = tauri::generate_context!();
let cli_config = context.config().tauri.cli.clone().unwrap();
match get_matches(&cli_config) {
// `matches` here is a Struct with { args, subcommand }.
// `args` is `HashMap<String, ArgData>` where `ArgData` is a struct with { value, occurances }.
// `subcommand` is `Option<Box<SubcommandMatches>>` where `SubcommandMatches` is a struct with { name, matches }.
Ok(matches) => {
println!("{:?}", matches)
}
Err(_) => {}
};
tauri::Builder::default()
.run(context)
.expect("error while running tauri application");
}
```
### JavaScript
```js
import { getMatches } from '@tauri-apps/api/cli'
getMatches().then((matches) => {
// do something with the { args, subcommand } matches
})
```
## Complete documentation
You can find more about the CLI configuration <a href="/docs/api/config#tauri">here</a>.

256
docs/guides/command.md
View File

@ -1,256 +0,0 @@
---
title: Create Rust Commands
---
import Alert from '@theme/Alert'
Tauri provides a simple yet powerful "command" system for calling Rust functions from your web app. Commands can accept arguments and return values. They can also return errors and be `async`.
## Basic Example
Commands are defined in your `src-tauri/src/main.rs` file. To create a command, just add a function and annotate it with `#[tauri::command]`:
```rust
#[tauri::command]
fn my_custom_command() {
println!("I was invoked from JS!");
}
```
You will have to provide a list of your commands to the builder function like so:
```rust
// Also in main.rs
fn main() {
tauri::Builder::default()
// This is where you pass in your commands
.invoke_handler(tauri::generate_handler![my_custom_command])
.run(tauri::generate_context!())
.expect("failed to run app");
}
```
Now, you can invoke the command from your JS code:
```js
// With the Tauri API npm package:
import { invoke } from '@tauri-apps/api/tauri'
// With the Tauri global script, enabled when `tauri.conf.json > build > withGlobalTauri` is set to true:
const invoke = window.__TAURI__.invoke
// Invoke the command
invoke('my_custom_command')
```
## Passing Arguments
Your command handlers can take arguments:
```rust
#[tauri::command]
fn my_custom_command(invoke_message: String) {
println!("I was invoked from JS, with this message: {}", invoke_message);
}
```
Arguments should be passed as a JSON object with camelCase keys:
```js
invoke('my_custom_command', { invokeMessage: 'Hello!' })
```
Arguments can be of any type, as long as they implement [serde::Deserialize](https://serde.rs/derive.html).
## Returning Data
Command handlers can return data as well:
```rust
#[tauri::command]
fn my_custom_command() -> String {
"Hello from Rust!".into()
}
```
The `invoke` function returns a promise that resolves with the returned value:
```js
invoke('my_custom_command').then((message) => console.log(message))
```
Returned data can be of any type, as long as it implements [Serde::Serialize](https://serde.rs/derive.html).
## Error Handling
If your handler could fail and needs to be able to return an error, have the function return a `Result`:
```rust
#[tauri::command]
fn my_custom_command() -> Result<String, String> {
// If something fails
Err("This failed!".into())
// If it worked
Ok("This worked!".into())
}
```
If the command returns an error, the promise will reject, otherwise it resolves:
```js
invoke('my_custom_command')
.then((message) => console.log(message))
.catch((error) => console.error(error))
```
## Async Commands
<Alert title="Note">
Async commands are executed on a separate thread using the <a href="https://tauri.studio/en/docs/api/rust/tauri/async_runtime/fn.spawn">async runtime</a>.
Commands without the <i>async</i> keyword are executed on the main thread, unless defined with <i>#[tauri::command(async)]</i>.
</Alert>
If your command needs to run asynchronously, simply declare it as `async`:
```rust
#[tauri::command]
async fn my_custom_command() {
// Call another async function and wait for it to finish
let result = some_async_function().await;
println!("Result: {}", result);
}
```
Since invoking the command from JS already returns a promise, it works just like any other command:
```js
invoke('my_custom_command').then(() => console.log('Completed!'))
```
## Accessing the Window in Commands
Commands can access the `Window` instance that invoked the message:
```rust
#[tauri::command]
async fn my_custom_command(window: tauri::Window) {
println!("Window: {}", window.label());
}
```
## Accessing an AppHandle in Commands
Commands can access an `AppHandle` instance:
```rust
#[tauri::command]
async fn my_custom_command(app_handle: tauri::AppHandle) {
let app_dir = app_handle.path_resolver().app_dir();
use tauri::GlobalShortcutManager;
app_handle.global_shortcut_manager().register("CTRL + U", move || {});
}
```
## Accessing managed state
Tauri can manage state using the `manage` function on `tauri::Builder`.
The state can be accessed on a command using `tauri::State`:
```rust
struct MyState(String);
#[tauri::command]
fn my_custom_command(state: tauri::State<MyState>) {
assert_eq!(state.0 == "some state value", true);
}
fn main() {
tauri::Builder::default()
.manage(MyState("some state value".into()))
.invoke_handler(tauri::generate_handler![my_custom_command])
.run(tauri::generate_context!())
.expect("error while running tauri application");
}
```
## Creating Multiple Commands
The `tauri::generate_handler!` macro takes an array of commands. To register
multiple commands, you cannot call invoke_handler multiple times. Only the last
call will be used. You must pass each command to a single call of
`tauri::generate_handler!`.
```rust
#[tauri::command]
fn cmd_a() -> String {
"Command a"
}
#[tauri::command]
fn cmd_b() -> String {
"Command b"
}
fn main() {
tauri::Builder::default()
.invoke_handler(tauri::generate_handler![cmd_a, cmd_b])
.run(tauri::generate_context!())
.expect("error while running tauri application");
}
```
## Complete Example
Any or all of the above features can be combined:
```rust title=main.rs
// Definition in main.rs
struct Database;
#[derive(serde::Serialize)]
struct CustomResponse {
message: String,
other_val: usize,
}
async fn some_other_function() -> Option<String> {
Some("response".into())
}
#[tauri::command]
async fn my_custom_command(
window: tauri::Window,
number: usize,
database: tauri::State<'_, Database>,
) -> Result<CustomResponse, String> {
println!("Called from {}", window.label());
let result: Option<String> = some_other_function().await;
if let Some(message) = result {
Ok(CustomResponse {
message,
other_val: 42 + number,
})
} else {
Err("No result".into())
}
}
fn main() {
tauri::Builder::default()
.manage(Database {})
.invoke_handler(tauri::generate_handler![my_custom_command])
.run(tauri::generate_context!())
.expect("error while running tauri application");
}
```
```js
// Invocation from JS
invoke('my_custom_command', {
number: 42,
})
.then((res) =>
console.log(`Message: ${res.message}, Other Val: ${res.other_val}`)
)
.catch((e) => console.error(e))
```

52
docs/guides/contributor-guide.md
View File

@ -1,52 +0,0 @@
---
title: Contributor Guide
---
todo: make this friendlier and more complete
Tauri is a polyglot system that uses:
- git
- Node.js
- Rust
- GitHub actions
It can be developed on macOS, Linux and Windows.
## Contribution Flow
1. File an Issue
2. Fork the Repository
3. Make Your Changes
4. Make a PR
### A Note About Contributions to the Rust Libraries
When contributing to the Rust libraries `tauri`, `tauri-api`, and `tauri-updater`; you will want to setup an environment for RLS (the Rust Language Server). In the Tauri root directory, there is a `.scripts` folder that contains a set of scripts to automate adding a couple temporary environment variables to your shell/terminal. These environment variables point to directories in the test fixture which will prevent RLS from crashing on compile-time. This is a necessary step for setting up a development environment for Tauri's Rust libraries.
##### _Example Instructions_
1. Navigate to the Tauri Root directory.
2. Execute a script based on your Operating System from this folder: `.scripts/init_env.bat` for Windows Cmd, `.scripts/init_env.ps1` for Windows Powershell, `. .scripts/init_env.sh` for Linux/macOS bash (note the first `.` in this command).
3. Open your text editor/IDE from this shell/terminal.
## Hands On Example
Let's make a new example. That's a great way to learn. We are going to assume you are on a nixy type of environment like Linux or macOS and have all of your development dependencies like rust and node already sorted out.
```sh
git clone git@github.com:tauri-apps/tauri.git
cd tauri/cli/tauri.js
yarn
mkdir ../../examples/vanillajs && cd "$_"
```
```json
"tauri:source": "node ../../../cli/tauri.js/bin/tauri",
```
```ini
[dependencies.tauri]
path = "../../../../core/tauri"
features = [ "all-api" ]
```

132
docs/guides/events.md
View File

@ -1,132 +0,0 @@
---
title: Events
---
The Tauri event system is a multi-producer multi-consumer communication primitive that allows message passing between the frontend and the backend.
It is analogous to the command system, but payload type check must be written on the event handler and it simplifies communication from the backend to the frontend, working like a channel.
A Tauri application can listen and emit to global and window-specific events. Usage from the frontend and the backend are described below.
## Frontend
The event system is accessible on the frontend on the `event` and `window` modules of the `@tauri-apps/api` package.
### Global events
To use the global event channel, import the `event` module and use the `emit` and `listen` functions:
```ts
import { emit, listen } from '@tauri-apps/api/event'
// listen to the `click` event and get a function to remove the event listener
// there's also a `once` function that subscribes to an event and automatically unsubscribes the listener on the first event
const unlisten = await listen('click', event => {
// event.event is the event name (useful if you want to use a single callback fn for multiple event types)
// event.payload is the payload object
})
// emits the `click` event with the object payload
emit('click', {
theMessage: 'Tauri is awesome!'
})
```
### Window-specific events
Window-specific events are exposed on the `window` module.
```ts
import { appWindow, WebviewWindow } from '@tauri-apps/api/window'
// emit an event that are only visible to the current window
appWindow.emit('event', { message: 'Tauri is awesome!' })
// create a new webview window and emit an event only to that window
const webview = new WebviewWindow('window')
webview.emit('event')
```
## Backend
On the backend, the global event channel is exposed on the `App` struct, and window-specific events can be emitted using the `Window` trait.
### Global events
```rust
use tauri::Manager;
// the payload type must implement `Serialize`.
// for global events, it also must implement `Clone`.
#[derive(Clone, serde::Serialize)]
struct Payload {
message: String,
}
fn main() {
tauri::Builder::default()
.setup(|app| {
// listen to the `event-name` (emitted on any window)
let id = app.listen_global("event-name", |event| {
println!("got event-name with payload {:?}", event.payload());
});
// unlisten to the event using the `id` returned on the `listen_global` function
// an `once_global` API is also exposed on the `App` struct
app.unlisten(id);
// emit the `event-name` event to all webview windows on the frontend
app.emit_all("event-name", Payload { message: "Tauri is awesome!".into() }).unwrap();
Ok(())
})
.run(tauri::generate_context!())
.expect("failed to run app");
}
```
### Window-specific events
To use the window-specific event channel, a `Window` object can be obtained on a command handler or with the `get_window` function:
```rust
use tauri::{Manager, Window};
// the payload type must implement `Serialize`.
#[derive(serde::Serialize)]
struct Payload {
message: String,
}
// init a background process on the command, and emit periodic events only to the window that used the command
#[tauri::command]
fn init_process(window: Window) {
std::thread::spawn(move || {
loop {
window.emit("event-name", Payload { message: "Tauri is awesome!".into() }).unwrap();
}
});
}
fn main() {
tauri::Builder::default()
.setup(|app| {
// `main` here is the window label; it is defined on the window creation or under `tauri.conf.json`
// the default value is `main`. note that it must be unique
let main_window = app.get_window("main").unwrap();
// listen to the `event-name` (emitted on the `main` window)
let id = main_window.listen("event-name", |event| {
println!("got window event-name with payload {:?}", event.payload());
});
// unlisten to the event using the `id` returned on the `listen` function
// an `once` API is also exposed on the `Window` struct
main_window.unlisten(id);
// emit the `event-name` event to the `main` window
main_window.emit("event-name", Payload { message: "Tauri is awesome!".into() }).unwrap();
Ok(())
})
.invoke_handler(tauri::generate_handler![init_process])
.run(tauri::generate_context!())
.expect("failed to run app");
}
```

47
docs/guides/icons.md
View File

@ -1,47 +0,0 @@
---
title: Icons
---
import Command from '@theme/Command'
import Alert from '@theme/Alert'
Tauri ships with a default iconset based on its logo. This is probably NOT what you want when you ship your application. To remedy this common situation, Tauri provides the `icon` command that will take an input file ("./app-icon.png" by default) and create all the icons needed for the various platforms:
<Command name="icon"/>
```sh
Options
--help, -h Displays this message
--log, l Logging [boolean]
--icon, i Source icon (png, 1240x1240 with transparency)
--target, t Target folder (default: 'src-tauri/icons')
--compression, c Compression type [pngquant|optipng|zopfli]
```
These will be placed in your `src-tauri/icons` folder where they will automatically be included in your built app.
If you need to source your icons from some other location, you can edit this part of the `src-tauri/tauri.conf.json` file:
```json
{
"tauri": {
"bundle": {
"icon": [
"icons/32x32.png",
"icons/128x128.png",
"icons/128x128@2x.png",
"icons/icon.icns",
"icons/icon.ico"
]
}
}
}
```
<Alert type="info" icon="info-alt" title="Note on filetypes">
- icon.icns = macOS
- icon.ico = MS Windows
- \*.png = Linux
</Alert>

158
docs/guides/menu.md
View File

@ -1,158 +0,0 @@
---
title: Window Menu
---
Native application menus can be attached to a window.
### Creating a menu
To create a native window menu, import the `Menu`, `Submenu`, `MenuItem` and `CustomMenuItem` types.
The `MenuItem` enum contains a collection of platform-specific items (currently not implemented on Windows).
The `CustomMenuItem` allows you to create your own menu items and add special functionality to them.
```rust
use tauri::{CustomMenuItem, Menu, MenuItem, Submenu};
```
Create a `Menu` instance:
```rust
// here `"quit".to_string()` defines the menu item id, and the second parameter is the menu item label.
let quit = CustomMenuItem::new("quit".to_string(), "Quit");
let close = CustomMenuItem::new("close".to_string(), "Close");
let submenu = Submenu::new("File", Menu::new().add_item(quit).add_item(close));
let menu = Menu::new()
.add_native_item(MenuItem::Copy)
.add_item(CustomMenuItem::new("hide", "Hide"))
.add_submenu(submenu);
// alternatively, using the `with_items` constructor, useful if you end up using conditional compilation
let menu = Menu::with_items([
MenuItem::Copy.into(),
CustomMenuItem::new("hide", "Hide").into(),
submenu.into(),
])
```
### Adding the menu to all windows
The defined menu can be set to all windows using the `menu` API on the `tauri::Builder` struct:
```rust
use tauri::{CustomMenuItem, Menu, MenuItem, Submenu};
fn main() {
let menu = Menu::new(); // configure the menu
tauri::Builder::default()
.menu(menu)
.run(tauri::generate_context!())
.expect("error while running tauri application");
}
```
### Adding the menu to a specific window
You can create a window and set the menu to be used. This allows defining a specific menu set for each application window.
```rust
use tauri::{CustomMenuItem, Menu, MenuItem, Submenu};
use tauri::WindowBuilder;
fn main() {
let menu = Menu::new(); // configure the menu
tauri::Builder::default()
.create_window(
"main-window".to_string(),
tauri::WindowUrl::App("index.html".into()),
move |window_builder, webview_attributes| {
(window_builder.menu(menu), webview_attributes)
},
)
.run(tauri::generate_context!())
.expect("error while running tauri application");
}
```
### Listening to events on custom menu items
Each `CustomMenuItem` triggers an event when clicked. Use the `on_menu_event` API to handle them, either on the global `tauri::Builder` or on an specific window.
#### Listening to events on global menus
```rust
use tauri::{CustomMenuItem, Menu, MenuItem};
fn main() {
let menu = vec![]; // insert the menu array here
tauri::Builder::default()
.menu(menu)
.on_menu_event(|event| {
match event.menu_item_id() {
"quit" => {
std::process::exit(0);
}
"close" => {
event.window().close().unwrap();
}
_ => {}
}
})
.run(tauri::generate_context!())
.expect("error while running tauri application");
}
```
#### Listening to events on window menus
```rust
use tauri::{CustomMenuItem, Menu, MenuItem};
use tauri::{Manager, WindowBuilder};
fn main() {
let menu = vec![]; // insert the menu array here
tauri::Builder::default()
.create_window(
"main-window".to_string(),
tauri::WindowUrl::App("index.html".into()),
move |window_builder, webview_attributes| {
(window_builder.menu(menu), webview_attributes)
},
)
.setup(|app| {
let window = app.get_window("main-window").unwrap();
let window_ = window.clone();
window.on_menu_event(move |event| {
match event.menu_item_id().as_str() {
"quit" => {
std::process::exit(0);
}
"close" => {
window_.close().unwrap();
}
_ => {}
}
});
Ok(())
})
.run(tauri::generate_context!())
.expect("error while running tauri application");
}
```
### Updating menu items
The `Window` struct has a `menu_handle` method, which allows updating menu items:
```rust
fn main() {
tauri::Builder::default()
.setup(|app| {
let main_window = app.get_window("main").unwrap();
let menu_handle = main_window.menu_handle();
std::thread::spawn(move || {
// you can also `set_selected`, `set_enabled` and `set_native_image` (macOS only).
menu_handle.get_item("item_id").set_title("New title");
})
Ok(())
})
}
```

335
docs/guides/migration.md
View File

@ -1,335 +0,0 @@
---
title: Migrating from 0.x
---
First of all if you still have `tauri` as dependency in your `package.json`
replace it with a recent version of `@tauri-apps/cli` (make sure to also change
the import path in your JavaScript/TypeScript files, see [JavaScript](#javascript)).
For example:
```diff
- "tauri": "^0.14.1"
+ "@tauri-apps/cli": "^1.0.0-beta-rc.4"
```
Next update your `Cargo.toml`:
- add `tauri-build` as a new build-dependency and remove `winres`, e.g.:
```diff
+ [build-dependencies]
+ tauri-build = { version = "1.0.0-beta-rc.0" }
- [target."cfg(windows)".build-dependencies]
- winres = "0.1"
```
- update the version of `tauri` to e.g. `1.0.0-beta-rc.4`
- remove all old features of the `tauri` dependency
- remove all features, that tauri added and add `custom-protocol` as a new one:
```diff
[features]
- embedded-server = [ "tauri/embedded-server" ]
- no-server = [ "tauri/no-server" ]
+ custom-protocol = [ "tauri/custom-protocol" ]
+ default = [ "custom-protocol" ]
```
Update your `tauri.conf.json` like this:
- remove `ctx`
- remove the `embeddedServer`
- rename `osx` to `macOS` and add some fields:
- `"exceptionDomain": ""`
- `"signingIdentity": null`
- `"entitlements": null`
- remove the `exceptionDomain`
- add a configuration for `windows`:
- `"certificateThumbprint": null`
- `"digestAlgorithm": "sha256"`
- `"timestampUrl": ""`
- make the `window` definition into an array and call it `windows`
- remove `inliner`
> for more information about the config see [here](../api/config.md)
```diff
{
- "ctx": {},
"tauri": {
- "embeddedServer": {
- "active": true
- },
"bundle": {
- "osx": {
+ "macOS": {
"frameworks": [],
"minimumSystemVersion": "",
- "useBootstrapper": false
+ "useBootstrapper": false,
+ "exceptionDomain": "",
+ "signingIdentity": null,
+ "entitlements": null
},
- "exceptionDomain": ""
+ "windows": {
+ "certificateThumbprint": null,
+ "digestAlgorithm": "sha256",
+ "timestampUrl": ""
+ }
},
+ "updater": {
+ "active": false
+ },
- "window": {
+ "windows": [
{
"title": "Calciumdibromid",
"width": 800,
"height": 600,
"resizable": true,
"fullscreen": false
}
+ ],
- "inliner": {
- "active": true
- }
}
}
```
## Commands
The following example is taken from the previous documentation.
In the new version of Tauri there is no distinction between synchronous and
asynchronous commands, the only difference in your code is a call of
`tauri::execute_promise()`, that isn't there in a synchronous command.
### Rust
Here is the complete example code of the "old" version:
```rust
use serde::{Deserialize, Serialize};
#[derive(Deserialize)]
struct DoSomethingPayload {
state: String,
data: u64,
}
#[derive(Deserialize)]
#[serde(tag = "cmd", rename_all = "camelCase")]
enum Cmd {
DoSomething {
count: u64,
payload: DoSomethingPayload,
callback: String,
error: String,
},
}
#[derive(Serialize)]
struct Response<'a> {
value: u64,
message: &'a str,
}
#[derive(Debug, Clone)]
struct CommandError<'a> {
message: &'a str,
}
impl<'a> CommandError<'a> {
fn new(message: &'a str) -> Self {
Self { message }
}
}
impl<'a> std::fmt::Display for CommandError<'a> {
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
write!(f, "{}", self.message)
}
}
impl<'a> std::error::Error for CommandError<'a> {}
fn main() {
tauri::AppBuilder::new()
.invoke_handler(|_webview, arg| {
use Cmd::*;
match serde_json::from_str(arg) {
Err(e) => Err(e.to_string()),
Ok(command) => {
match command {
DoSomething { count, payload, callback, error } => tauri::execute_promise(
_webview,
move || {
if count > 5 {
let response = Response {
value: 5,
message: "async response!",
};
Ok(response)
} else {
Err(CommandError::new("count should be > 5").into())
}
},
callback,
error,
),
}
Ok(())
}
}
})
.build()
.run();
}
```
Complete the following steps to migrate your code:
- create a new function for every `Cmd` enum variant
- wrap the new function with the `#[tauri::command]` macro
- use the fields of the enum as arguments (`callback` and `error` can be deleted)
- as function body use the code inside the `match` block of the enum variant
- add a return type
- rename `AppBuilder` to `Builder` in `main()`
- replace the big `invoke_handler` with the new syntax
The old example code should look like this now:
```rust
use serde::{Deserialize, Serialize};
#[derive(Deserialize)]
struct DoSomethingPayload {
state: String,
data: u64,
}
#[derive(Serialize)]
struct Response<'a> {
value: u64,
message: &'a str,
}
#[derive(Debug, Clone, Serialize)]
struct CommandError<'a> {
message: &'a str,
}
impl<'a> CommandError<'a> {
fn new(message: &'a str) -> Self {
Self { message }
}
}
impl<'a> std::fmt::Display for CommandError<'a> {
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
write!(f, "{}", self.message)
}
}
impl<'a> std::error::Error for CommandError<'a> {}
#[tauri::command]
fn do_something(count: u64, payload: DoSomethingPayload) -> Result<Response, CommandError> {
if count > 5 {
let response = Response {
value: 5,
message: "async response!",
};
Ok(response)
} else {
Err(CommandError::new("count should be > 5").into())
}
}
fn main() {
tauri::Builder::new()
.invoke_handler(tauri::generate_handler![do_something])
.run(tauri::generate_context!());
}
```
### JavaScript
Like mentioned above there is also no distinction between synchronous and
asynchronous commands in JavaScript.
You only have to use `invoke` and optionally use the results.
Here is an example of the "old" code:
```js
invoke({
cmd: 'doSomething',
count: 5,
payload: {
state: 'some string data',
data: 17
}
});
promisified({
cmd: 'doSomething',
count: 5,
payload: {
state: 'some string data',
data: 17
}
}).then(response => {
console.log(response);
}).catch(error => {
console.error(error);
});
```
Complete the following steps to migrate your code:
- replace all `promisified`-calls with `invoke`-calls
- extract the `cmd` attribute of the argument object as first parameter
(you may have to rename it to `snake_case` as the `cmd` parameter is now the
name of the function in Rust)
- if you import parts of the tauri-api with `tauri/api/*` replace it with `@tauri-apps/api/*`, e.g.:
```diff
- import { invoke } from 'tauri/api/tauri';
+ import { invoke } from '@tauri-apps/api/tauri';
```
The old example code should look like this now:
```js
invoke(
'do_something',
{
count: 5,
payload: {
state: 'some string data',
data: 17
}
}
);
invoke(
'do_something',
{
count: 5,
payload: {
state: 'some string data',
data: 17
}
}
).then(response => {
console.log(response);
}).catch(error => {
console.error(error);
});
```
For more information on commands read [Create Rust Commands](command.md).

5
docs/guides/multiwindow.md
View File

@ -1,5 +0,0 @@
---
title: Multiwindow
---
Manage multiple windows on a single application.

9
docs/guides/patterns/about-patterns.md
View File

@ -1,9 +0,0 @@
---
id: about-patterns
title: "A word on patterns"
sidebar_label: A word on patterns
---
Tauri patterns are descriptions of use-cases that are entirely configurable within the `src-tauri/tauri.conf.json` file. These are not the limits of what Tauri can do, and there are probably more out there. If you discover one, why not get in touch and help us update this collection!
If you haven't read about the general design of Tauri, then it would make the most sense for you to visit the ["Get started"](/docs/get-started/intro) and become familiar with the basic architecture and terminology used in these patterns.

102
docs/guides/patterns/bridge.md
View File

@ -1,102 +0,0 @@
---
title: Bridge
---
import Rater from '@theme/Rater'
import useBaseUrl from '@docusaurus/useBaseUrl'
<div className="row">
<div className="col col--4">
<table>
<tr>
<td>Ease of Use</td>
<td><Rater value="3"/></td>
</tr>
<tr>
<td>Extensibility</td>
<td><Rater value="5"/></td>
</tr>
<tr>
<td>Performance</td>
<td><Rater value="4"/></td>
</tr>
<tr>
<td>Security</td>
<td><Rater value="4"/></td>
</tr>
</table>
</div>
<div className="col col--4 pattern-logo">
<img src={useBaseUrl('img/patterns/Bridge.png')} alt="Bridge" />
</div>
<div className="col col--4">
Pros:
<ul>
<li>Highly configurable</li>
<li>No Rust skills required</li>
</ul>
Cons:
<ul>
<li>Some WebAPIs unavailable</li>
<li>Challenge to implement</li>
</ul>
</div>
</div>
## Description
The Bridge recipe is a secure pattern where messages are passed between brokers via an implicit bridge using the API. It isolates functionality to scope and passes messages instead of functionality.
## Diagram
import Mermaid, { colors } from '@theme/Mermaid'
<Mermaid chart={`graph TD
H==>F
subgraph WEBVIEW
F-.-E
end
D-->E
E-->D
B-->D
D-->B
subgraph RUST
A==>H
A-->B
B-.-C
B-.-G
end
A[Binary]
B{Rust Broker}
C[Subprocess 2]
G[Subprocess 1]
D(( API BRIDGE ))
E{JS Broker}
F[Window]
H{Bootstrap}
style D fill:#ccc,stroke:#333,stroke-width:4px,color:white
style RUST fill:${colors.orange.light},stroke:${colors.orange.dark},stroke-width:4px
style WEBVIEW fill:${colors.blue.light},stroke:${colors.blue.dark},stroke-width:4px`} />
## Configuration
Here's what you need to add to your tauri.conf.json file:
```json
"tauri": {
"allowlist": { // all API values are default false
"all": false, // use this flag to enable all API features
"shell": {
"execute": false, // enable application execution
"open": false, // open link/path in the default app
},
"fs": {
"listFiles": false, // list files in a directory
"readBinaryFile": false, // read binary file from local filesystem
"readTextFile": false, // read text file from local filesystem
"setTitle": false, // set the window title
"writeFile": false // write file to local filesystem
}
}
}
```

102
docs/guides/patterns/cloudbridge.md
View File

@ -1,102 +0,0 @@
---
title: Cloudbridge
---
import Rater from '@theme/Rater'
import useBaseUrl from '@docusaurus/useBaseUrl'
<div className="row">
<div className="col col--4">
<table>
<tr>
<td>Ease of Use</td>
<td><Rater value="1"/></td>
</tr>
<tr>
<td>Extensibility</td>
<td><Rater value="5"/></td>
</tr>
<tr>
<td>Performance</td>
<td><Rater value="3"/></td>
</tr>
<tr>
<td>Security</td>
<td><Rater value="2"/></td>
</tr>
</table>
</div>
<div className="col col--4 pattern-logo">
<img src={useBaseUrl('img/patterns/Cloudbridge.png')} alt="Cloudbridge" />
</div>
<div className="col col--4">
Pros:
<ul>
<li>All available features</li>
<li>No Rust skills required</li>
</ul>
Cons:
<ul>
<li>Largest bundle size</li>
<li>Hard to separate concerns</li>
</ul>
</div>
</div>
## Description
The Cloudbridge recipe combines the flexibility of a localhost and the security of the bridge. With so many features, it can be easy to get lost.
## Diagram
import Mermaid, { colors } from '@theme/Mermaid'
<Mermaid chart={`graph TD
H==>F2
H==>D2
D2-->F2
F2-->D2
B-->D
D-->B
E2-->D
D-->E2
subgraph WEBVIEW
F2
E2
end
subgraph SERVER
D2
E-->D2
end
subgraph RUST
A==>H
A-->B
B-.-C
end
A[Binary]
B{Rust Broker}
C[Subprocess]
D(( API BRIDGE ))
E{JS Broker}
D2(( localhost ))
E[bundled resources]
E2{JS Broker}
F2[Window]
H{Bootstrap}
style D fill:#ccc,stroke:#333,stroke-width:4px,color:white
style RUST fill:${colors.orange.light},stroke:${colors.orange.dark},stroke-width:4px
style WEBVIEW fill:${colors.blue.light},stroke:${colors.blue.dark},stroke-width:4px
style SERVER fill:#49A24A,stroke:#2B6063,stroke-width:4px
`} />
## Configuration
Here's what you need to add to your tauri.conf.json file:
```json
"tauri": {
"allowlist": {
"all": true // enable entire API
}
}
```

89
docs/guides/patterns/cloudish.md
View File

@ -1,89 +0,0 @@
---
title: Cloudish
---
import Rater from '@theme/Rater'
import useBaseUrl from '@docusaurus/useBaseUrl'
<div className="row">
<div className="col col--4">
<table>
<tr>
<td>Ease of Use</td>
<td><Rater value="5"/></td>
</tr>
<tr>
<td>Extensibility</td>
<td><Rater value="3"/></td>
</tr>
<tr>
<td>Performance</td>
<td><Rater value="3"/></td>
</tr>
<tr>
<td>Security</td>
<td><Rater value="2"/></td>
</tr>
</table>
</div>
<div className="col col--4 pattern-logo">
<img src={useBaseUrl('img/patterns/Cloudish.png')} alt="Cloudish" />
</div>
<div className="col col--4">
Pros:
<ul>
<li>Similar to a SPA web-app</li>
<li>No Rust skills required</li>
</ul>
Cons:
<ul>
<li>No access to Rust API</li>
<li>Uses a localhost server</li>
</ul>
</div>
</div>
## Description
The Cloudish recipe is a pattern for maximum flexibility and app performance. It uses a localhost server, which means that your app will technically be available to other processes, like browsers and potentially other devices on the network. All of your assets are baked into the binary, but served as if they were distinct files.
## Diagram
import Mermaid, { colors } from '@theme/Mermaid'
<Mermaid chart={`graph TD
H==>F
H==>D
D-->F
F-->D
subgraph RUST
A==>H
end
subgraph WEBVIEW
F
end
subgraph SERVER
D
E-->D
end
A[Binary]
D(( localhost ))
E[bundled resources]
F[Window]
H{Bootstrap}
style RUST fill:${colors.orange.light},stroke:${colors.orange.dark},stroke-width:4px
style WEBVIEW fill:${colors.blue.light},stroke:${colors.blue.dark},stroke-width:4px
style SERVER fill:#49A24A,stroke:#2B6063,stroke-width:4px`} />
## Configuration
Here's what you need to add to your tauri.conf.json file:
```json
"tauri": {
"allowlist": {
"all": false // disable entire API
}
}
```

91
docs/guides/patterns/glui.md
View File

@ -1,91 +0,0 @@
---
title: GLUI
---
import Alert from '@theme/Alert'
import useBaseUrl from '@docusaurus/useBaseUrl'
<Alert type="warning" icon="info-alt" title="Please note">
This pattern is not available for now.
</Alert>
import Rater from '@theme/Rater'
<div className="row">
<div className="col col--4">
<table>
<tr>
<td>Ease of Use</td>
<td><Rater value="0"/></td>
</tr>
<tr>
<td>Extensibility</td>
<td><Rater value="0"/></td>
</tr>
<tr>
<td>Performance</td>
<td><Rater value="5"/></td>
</tr>
<tr>
<td>Security</td>
<td><Rater value="0"/></td>
</tr>
</table>
</div>
<div className="col col--4 pattern-logo">
<img src={useBaseUrl('img/patterns/GLUI.png')} alt="GLUI" />
</div>
<div className="col col--4">
Pros:
<ul>
<li>Framebuffer FTW</li>
<li>Window events rigged</li>
</ul>
Cons:
<ul>
<li>Broken on your machine</li>
</ul>
</div>
</div>
## Description
The GLUI is a research pattern that we will use internally to test approaches using a GLUTIN window. We’re not sure yet if it will make the final cut as a bona fide alternative to WebView, although early tests with transparent and multiwindow are exciting.
## Diagram
import Mermaid, { colors } from '@theme/Mermaid'
<Mermaid chart={`graph TD
A==>H
H==>G
A-->D
D-->G
subgraph GLUTIN
G
end
subgraph RUST
A
end
A[Binary]
D(Framebuffer)
G[GL Window]
H{Bootstrap}
style GLUTIN stroke:${colors.blue.dark},stroke-width:4px
style RUST fill:${colors.orange.light},stroke:${colors.orange.dark},stroke-width:4px`} />
## Configuration
Here's what you need to add to your tauri.conf.json file:
```json
"tauri": {
"allowlist": { // all API endpoints are default false
"all": false, // disable the api
},
"window": { // not yet normative
"glutin": true,
"webview": false
}
}
```

79
docs/guides/patterns/hermit.md
View File

@ -1,79 +0,0 @@
---
title: Hermit
---
import Rater from '@theme/Rater'
import useBaseUrl from '@docusaurus/useBaseUrl'
<div className="row">
<div className="col col--4">
<table>
<tr>
<td>Ease of Use</td>
<td><Rater value="5"/></td>
</tr>
<tr>
<td>Extensibility</td>
<td><Rater value="0"/></td>
</tr>
<tr>
<td>Performance</td>
<td><Rater value="5"/></td>
</tr>
<tr>
<td>Security</td>
<td><Rater value="5"/></td>
</tr>
</table>
</div>
<div className="col col--4 pattern-logo">
<img src={useBaseUrl('img/patterns/Hermit.png')} alt="Hermit" />
</div>
<div className="col col--4">
Pros:
<ul>
<li>Quick to make</li>
<li>Smallest size</li>
</ul>
Cons:
<ul>
<li>No remote resources</li>
<li>No access to API</li>
</ul>
</div>
</div>
## Description
The Hermit recipe is a pattern for ultimate application isolation where all logic is self-contained in the Window and the binary exists merely to bootstrap the Window. There is no communication back to Rust from the Window, there is no localhost server, and the Window has no access to any remote resources. The Hermit is great for interactive Kiosk Mode and standalone HTML based games.
## Diagram
import Mermaid, { colors } from '@theme/Mermaid'
<Mermaid chart={`graph LR
A==>H
H==>F
subgraph WEBVIEW
F
end
subgraph RUST
A
end
A[fa:fa-cog Binary ]
F[fa:fa-window-maximize Window]
H{Bootstrap}
style RUST fill:${colors.orange.light},stroke:${colors.orange.dark},stroke-width:4px
style WEBVIEW fill:${colors.blue.light},stroke:${colors.blue.dark},stroke-width:4px`} />
## Configuration
Here's what you need to add to your tauri.conf.json file:
```json
"tauri": {
"allowlist": {
"all": false, // disable and tree-shake all api functions
}
}
```

82
docs/guides/patterns/lockdown.md
View File

@ -1,82 +0,0 @@
---
title: Lockdown
---
import Rater from '@theme/Rater'
import useBaseUrl from '@docusaurus/useBaseUrl'
<div className="row">
<div className="col col--4">
<table>
<tr>
<td>Ease of Use</td>
<td><Rater value="2"/></td>
</tr>
<tr>
<td>Extensibility</td>
<td><Rater value="4"/></td>
</tr>
<tr>
<td>Performance</td>
<td><Rater value="5"/></td>
</tr>
<tr>
<td>Security</td>
<td><Rater value="5" color="#fff04d"/></td>
</tr>
</table>
</div>
<div className="col col--4 pattern-logo">
<img src={useBaseUrl('img/patterns/Lockdown.png')} alt="Lockdown" />
</div>
<div className="col col--4">
Pros:
<ul>
<li>Highest security rating</li>
<li>Elegant and powerful</li>
</ul>
Cons:
<ul>
<li>Rust skills required</li>
<li>No remote resources</li>
</ul>
</div>
</div>
## Description
The Lockdown recipe is a minimal usage of the [Bridge pattern](/docs/guides/patterns/bridge), which only allows interaction between Rust and the Window via expiring JS Promise Closures that are injected into the Window by Rust and nulled as part of the callback.
## Diagram
import Mermaid, { colors } from '@theme/Mermaid'
<Mermaid chart={`graph TD
H==>F
G-.->B
B-->G
subgraph WEBVIEW
G-->F
end
subgraph RUST
A-->B
A==>H
end
A[Binary]
B[API:Event]
F[Window]
G((Promise Closure))
H{Bootstrap}
style RUST fill:${colors.orange.light},stroke:${colors.orange.dark},stroke-width:4px
style WEBVIEW fill:${colors.blue.light},stroke:${colors.blue.dark},stroke-width:4px`} />
## Configuration
Here's what you need to add to your tauri.conf.json file:
```json
"tauri": {
"allowlist": {} // all API endpoints are default false
}
```

92
docs/guides/patterns/multiwin.md
View File

@ -1,92 +0,0 @@
---
title: Multiwin
---
import Alert from '@theme/Alert'
import useBaseUrl from '@docusaurus/useBaseUrl'
import Rater from '@theme/Rater'
<div className="row">
<div className="col col--4">
<table>
<tr>
<td>Ease of Use</td>
<td><Rater value="4"/></td>
</tr>
<tr>
<td>Extensibility</td>
<td><Rater value="4"/></td>
</tr>
<tr>
<td>Performance</td>
<td><Rater value="3"/></td>
</tr>
<tr>
<td>Security</td>
<td><Rater value="5"/></td>
</tr>
</table>
</div>
<div className="col col--4 pattern-logo">
<img src={useBaseUrl('img/patterns/Multiwin.png')} alt="Multiwin" />
</div>
<div className="col col--4">
Pros:
<ul>
<li>Windows can be spawned or destroyed at runtime</li>
<li>Separation of concerns</li>
</ul>
Cons:
<ul>
<li>Somewhat complex</li>
</ul>
</div>
</div>
## Description
The Multiwin recipe will allow you to have multiple windows.
## Diagram
import Mermaid, { colors } from '@theme/Mermaid'
<Mermaid chart={`graph LR
A==>H
H==>F
H==>G
subgraph WEBVIEW
F
end
subgraph WINIT
G
end
subgraph RUST
A
end
A[Binary]
F[Window]
G[Window]
H{Bootstrap}
style WINIT stroke:${colors.blue.dark},stroke-width:4px
style RUST fill:${colors.orange.light},stroke:${colors.orange.dark},stroke-width:4px
style WEBVIEW fill:${colors.blue.light},stroke:${colors.blue.dark},stroke-width:4px`} />
## Configuration
Here's what you need to add to your tauri.conf.json file:
```json
"tauri": {
"allowlist": {}, // all API endpoints are default false
"windows": [{
"title": "Window1",
"label": "main",
}, {
"title": "Splash",
"label": "splashscreen"
}]
}
```

102
docs/guides/plugin.md
View File

@ -1,102 +0,0 @@
---
title: Write Tauri Plugins
---
import Alert from '@theme/Alert'
<Alert title="Note" icon="info-alt">
The Tauri CLI can bootstrap a Plugin project with the `$ tauri init plugin --name your-plugin-name` command.
It setups the recommended folder structure, optionally adding a TypeScript API wrapper with the `--api` flag.
</Alert>
Plugins allow you to hook into the Tauri application lifecycle and introduce new commands.
## Writing a Plugin
To write a plugin you just need to implement the `tauri::plugin::Plugin` trait:
```rust
use tauri::{plugin::{Plugin, Result as PluginResult}, Runtime, PageLoadPayload, Window, Invoke, AppHandle};
struct MyAwesomePlugin<R: Runtime> {
invoke_handler: Box<dyn Fn(Invoke<R>) + Send + Sync>,
// plugin state, configuration fields
}
// the plugin custom command handlers if you choose to extend the API.
#[tauri::command]
// this will be accessible with `invoke('plugin:awesome|initialize')`.
// where `awesome` is the plugin name.
fn initialize() {}
#[tauri::command]
// this will be accessible with `invoke('plugin:awesome|do_something')`.
fn do_something() {}
impl<R: Runtime> MyAwesomePlugin<R> {
// you can add configuration fields here,
// see https://doc.rust-lang.org/1.0.0/style/ownership/builders.html
pub fn new() -> Self {
Self {
invoke_handler: Box::new(tauri::generate_handler![initialize, do_something]),
}
}
}
impl<R: Runtime> Plugin<R> for MyAwesomePlugin<R> {
/// The plugin name. Must be defined and used on the `invoke` calls.
fn name(&self) -> &'static str {
"awesome"
}
/// The JS script to evaluate on initialization.
/// Useful when your plugin is accessible through `window`
/// or needs to perform a JS task on app initialization
/// e.g. "window.awesomePlugin = { ... the plugin interface }"
fn initialization_script(&self) -> Option<String> {
None
}
/// initialize plugin with the config provided on `tauri.conf.json > plugins > $yourPluginName` or the default value.
fn initialize(&mut self, app: &AppHandle<R>, config: serde_json::Value) -> PluginResult<()> {
Ok(())
}
/// Callback invoked when the Window is created.
fn created(&mut self, window: Window<R>) {}
/// Callback invoked when the webview performs a navigation.
fn on_page_load(&mut self, window: Window<R>, payload: PageLoadPayload) {}
/// Extend the invoke handler.
fn extend_api(&mut self, message: Invoke<R>) {
(self.invoke_handler)(message)
}
}
```
Note that each function on the `Plugin` trait is optional, except the `name` function.
## Using a plugin
To use a plugin, just pass an instance of the `MyAwesomePlugin` struct to the App's `plugin` method:
```rust
fn main() {
let awesome_plugin = MyAwesomePlugin::new();
tauri::Builder::default()
.plugin(awesome_plugin)
.run(tauri::generate_context!())
.expect("failed to run app");
}
```
## Official Tauri Plugins
- [Stronghold](https://github.com/tauri-apps/tauri-plugin-stronghold)
- [Authenticator](https://github.com/tauri-apps/tauri-plugin-authenticator)
- [Logging](https://github.com/tauri-apps/tauri-plugin-log)
- [SQL](https://github.com/tauri-apps/tauri-plugin-sql)
- [WebSocket](https://github.com/tauri-apps/tauri-plugin-websocket)
- [Restoring window state](https://github.com/tauri-apps/tauri-plugin-window-state)
- [Store](https://github.com/tauri-apps/tauri-plugin-store)

106
docs/guides/splashscreen.md
View File

@ -1,106 +0,0 @@
---
title: Splashscreen
---
import Link from '@docusaurus/Link'
If your webpage could take some time to load, or if you need to run an initialization procedure in Rust before displaying your main window, a splashscreen could improve the loading experience for the user.
### Setup
First, create a `splashscreen.html` in your `distDir` that contains the HTML code for a splashscreen. Then, update your `tauri.conf.json` like so:
```diff
"windows": [
{
"title": "Tauri App",
"width": 800,
"height": 600,
"resizable": true,
"fullscreen": false,
+ "visible": false // Hide the main window by default
},
// Add the splashscreen window
+ {
+ "width": 400,
+ "height": 200,
+ "decorations": false,
+ "url": "splashscreen.html",
+ "label": "splashscreen"
+ }
]
```
Now, your main window will be hidden and the splashscreen window will show when your app is launched. Next, you'll need a way to close the splashscreen and show the main window when your app is ready. How you do this depends on what you are waiting for before closing the splashscreen.
### Waiting for Webpage
If you are waiting for your web code, you'll want to create a `close_splashscreen` [command](command.md).
```rust title=src-tauri/main.rs
use tauri::Manager;
// Create the command:
#[tauri::command]
fn close_splashscreen(window: tauri::Window) {
// Close splashscreen
if let Some(splashscreen) = window.get_window("splashscreen") {
splashscreen.close().unwrap();
}
// Show main window
window.get_window("main").unwrap().show().unwrap();
}
// Register the command:
fn main() {
tauri::Builder::default()
// Add this line
.invoke_handler(tauri::generate_handler![close_splashscreen])
.run(tauri::generate_context!())
.expect("failed to run app");
}
```
Then, you can call it from your JS:
```js
// With the Tauri API npm package:
import { invoke } from '@tauri-apps/api/tauri'
// With the Tauri global script:
const invoke = window.__TAURI__.invoke
document.addEventListener('DOMContentLoaded', () => {
// This will wait for the window to load, but you could
// run this function on whatever trigger you want
invoke('close_splashscreen')
})
```
### Waiting for Rust
If you are waiting for Rust code to run, put it in the `setup` function handler so you have access to the `App` instance:
```rust title=src-tauri/main.rs
use tauri::Manager;
fn main() {
tauri::Builder::default()
.setup(|app| {
let splashscreen_window = app.get_window("splashscreen").unwrap();
let main_window = app.get_window("main").unwrap();
// we perform the initialization code on a new task so the app doesn't freeze
tauri::async_runtime::spawn(async move {
// initialize your app here instead of sleeping :)
println!("Initializing...");
std::thread::sleep(std::time::Duration::from_secs(2));
println!("Done initializing.");
// After it's done, close the splashscreen and display the main window
splashscreen_window.close().unwrap();
main_window.show().unwrap();
});
Ok(())
})
.run(tauri::generate_context!())
.expect("failed to run app");
}
```

184
docs/guides/system-tray.md
View File

@ -1,184 +0,0 @@
---
title: System Tray
---
Native application system tray.
### Setup
Configure the `systemTray` object on `tauri.conf.json`:
```json
{
"tauri": {
"systemTray": {
"iconPath": "icons/icon.png",
"iconAsTemplate": true
}
}
}
```
The `iconPath` is pointed to a PNG file on macOS and Linux, and a `.ico` file must exist for Windows support.
The `iconAsTemplate` is a boolean value that determines whether the image represents a [template](https://developer.apple.com/documentation/appkit/nsimage/1520017-template?language=objc) image on macOS.
### Creating a system tray
To create a native system tray, import the `SystemTray` type:
```rust
use tauri::SystemTray;
```
Initialize a new tray instance:
```rust
let tray = SystemTray::new();
```
### Configuring a system tray context menu
Optionally you can add a context menu that is visible when the tray icon is right clicked. Import the `SystemTrayMenu`, `SystemTrayMenuItem` and `CustomMenuItem` types:
```rust
use tauri::{CustomMenuItem, SystemTrayMenu, SystemTrayMenuItem};
```
Create the `SystemTrayMenu`:
```rust
// here `"quit".to_string()` defines the menu item id, and the second parameter is the menu item label.
let quit = CustomMenuItem::new("quit".to_string(), "Quit");
let hide = CustomMenuItem::new("hide".to_string(), "Hide");
let tray_menu = SystemTrayMenu::new()
.add_item(quit)
.add_native_item(SystemTrayMenuItem::Separator)
.add_item(hide);
```
Add the tray menu to the `SystemTray` instance:
```rust
let tray = SystemTray::new().with_menu(tray_menu);
```
### Configure the app system tray
The created `SystemTray` instance can be set using the `system_tray` API on the `tauri::Builder` struct:
```rust
use tauri::{CustomMenuItem, SystemTray, SystemTrayMenu};
fn main() {
let tray_menu = SystemTrayMenu::new(); // insert the menu items here
let system_tray = SystemTray::new()
.with_menu(tray_menu);
tauri::Builder::default()
.system_tray(system_tray)
.run(tauri::generate_context!())
.expect("error while running tauri application");
}
```
### Listening to system tray events
Each `CustomMenuItem` triggers an event when clicked.
Also, Tauri emits tray icon click events.
Use the `on_system_tray_event` API to handle them:
```rust
use tauri::{CustomMenuItem, SystemTray, SystemTrayMenu};
use tauri::Manager;
fn main() {
let tray_menu = SystemTrayMenu::new(); // insert the menu items here
tauri::Builder::default()
.system_tray(SystemTray::new().with_menu(tray_menu))
.on_system_tray_event(|app, event| match event {
SystemTrayEvent::LeftClick {
position: _,
size: _,
..
} => {
println!("system tray received a left click");
}
SystemTrayEvent::RightClick {
position: _,
size: _,
..
} => {
println!("system tray received a right click");
}
SystemTrayEvent::DoubleClick {
position: _,
size: _,
..
} => {
println!("system tray received a double click");
}
SystemTrayEvent::MenuItemClick { id, .. } => {
match id.as_str() {
"quit" => {
std::process::exit(0);
}
"hide" => {
let window = app.get_window("main").unwrap();
window.hide().unwrap();
}
_ => {}
}
}
_ => {}
})
.run(tauri::generate_context!())
.expect("error while running tauri application");
}
```
### Updating system tray
The `AppHandle` struct has a `tray_handle` method, which returns a handle to the system tray allowing updating tray icon and context menu items:
#### Updating context menu items
```rust
use tauri::{CustomMenuItem, SystemTray, SystemTrayMenu};
use tauri::Manager;
fn main() {
let tray_menu = SystemTrayMenu::new(); // insert the menu items here
tauri::Builder::default()
.system_tray(SystemTray::new().with_menu(tray_menu))
.on_system_tray_event(|app, event| match event {
SystemTrayEvent::MenuItemClick { id, .. } => {
// get a handle to the clicked menu item
// note that `tray_handle` can be called anywhere,
// just get a `AppHandle` instance with `app.handle()` on the setup hook
// and move it to another function or thread
let item_handle = app.tray_handle().get_item(&id);
match id.as_str() {
"hide" => {
let window = app.get_window("main").unwrap();
window.hide().unwrap();
// you can also `set_selected`, `set_enabled` and `set_native_image` (macOS only).
item_handle.set_title("Show").unwrap();
}
_ => {}
}
}
_ => {}
})
.run(tauri::generate_context!())
.expect("error while running tauri application");
}
```
#### Updating tray icon
Note that `tauri::Icon` must be a `Path` variant on Linux, and `Raw` variant on Windows and macOS.
```rust
app.tray_handle().set_icon(tauri::Icon::Raw(include_bytes!("../path/to/myicon.ico"))).unwrap();
```

308
docs/guides/updater.md
View File

@ -1,308 +0,0 @@
---
title: Updater
---
# Configuration
Once you have your Tauri project ready, you need to configure the updater.
Add this in tauri.conf.json
```json
"updater": {
"active": true,
"endpoints": [
"https://releases.myapp.com/{{target}}/{{current_version}}"
],
"dialog": true,
"pubkey": ""
}
```
The required keys are "active" and "endpoints", others are optional.
"active" must be a boolean. By default, it's set to false.
"endpoints" must be an array. The string `{{target}}` and `{{current_version}}` are automatically replaced in the URL allowing you determine [server-side](#update-server-json-format) if an update is available. If multiple endpoints are specified, the updater will fallback if a server is not responding within the pre-defined timeout.
"dialog" if present must be a boolean. By default, it's set to true. If enabled, [events](#events) are turned-off as the updater will handle everything. If you need the custom events, you MUST turn off the built-in dialog.
"pubkey" if present must be a valid public-key generated with Tauri cli. See [Signing updates](#signing-updates).
## Update Requests
Tauri is indifferent to the request the client application provides for update checking.
`Accept: application/json` is added to the request headers because Tauri is responsible for parsing the response.
For the requirements imposed on the responses and the body format of an update, response see [Server Support](#server-support).
Your update request must *at least* include a version identifier so that the server can determine whether an update for this specific version is required.
It may also include other identifying criteria such as operating system version, to allow the server to deliver as fine-grained an update as you would like.
How you include the version identifier or other criteria is specific to the server that you are requesting updates from. A common approach is to use query parameters, [Configuration](#configuration) shows an example of this.
## Built-in dialog
By default, updater uses a built-in dialog API from Tauri.
![New Update](https://i.imgur.com/UMilB5A.png)
The dialog release notes is represented by the update `note` provided by the [server](#server-support).
If the user accepts, the download and install are initialized. The user will be then prompted to restart the application.
## Javascript API
**Attention, you need to _disable built-in dialog_ in your [tauri configuration](#configuration), otherwise, events aren't emitted and the javascript API will NOT work.**
```js
import { checkUpdate, installUpdate } from "@tauri-apps/api/updater";
import { relaunch } from "@tauri-apps/api/process";
try {
const {shouldUpdate, manifest} = await checkUpdate();
if (shouldUpdate) {
// display dialog
await installUpdate();
// install complete, restart app
await relaunch();
}
} catch(error) {
console.log(error);
}
```
## Events
**Attention, you need to _disable built-in dialog_ in your [tauri configuration](#configuration), otherwise, events aren't emitted.**
To know when an update is ready to be installed, you can subscribe to these events:
### Initialize updater and check if a new version is available
#### If a new version is available, the event `tauri://update-available` is emitted.
Event: `tauri://update`
### Rust
```rust
window.emit("tauri://update".to_string(), None);
```
### Javascript
```js
import { emit } from "@tauri-apps/api/event";
emit("tauri://update");
```
### Listen New Update Available
Event: `tauri://update-available`
Emitted data:
```none
version Version announced by the server
date Date announced by the server
body Note announced by the server
```
### Rust
```rust
window.listen("tauri://update-available".to_string(), move |msg| {
println!("New version available: {:?}", msg);
})
```
### Javascript
```js
import { listen } from "@tauri-apps/api/event";
listen("tauri://update-available", function (res) {
console.log("New version available: ", res);
});
```
### Emit Install and Download
You need to emit this event to initialize the download and listen to the [install progress](#listen-install-progress).
Event: `tauri://update-install`
### Rust
```rust
window.emit("tauri://update-install".to_string(), None);
```
### Javascript
```js
import { emit } from "@tauri-apps/api/event";
emit("tauri://update-install");
```
### Listen Install Progress
Event: `tauri://update-status`
Emitted data:
```none
status [ERROR/PENDING/DONE]
error String/null
```
PENDING is emitted when the download is started and DONE when the install is complete. You can then ask to restart the application.
ERROR is emitted when there is an error with the updater. We suggest to listen to this event even if the dialog is enabled.
### Rust
```rust
window.listen("tauri://update-status".to_string(), move |msg| {
println!("New status: {:?}", msg);
})
```
### Javascript
```js
import { listen } from "@tauri-apps/api/event";
listen("tauri://update-status", function (res) {
console.log("New status: ", res);
});
```
# Server Support
Your server should determine whether an update is required based on the [Update Request](#update-requests) your client issues.
If an update is required your server should respond with a status code of [200 OK](http://tools.ietf.org/html/rfc2616#section-10.2.1) and include the [update JSON](#update-server-json-format) in the body. To save redundantly downloading the same version multiple times your server must not inform the client to update.
If no update is required your server must respond with a status code of [204 No Content](http://tools.ietf.org/html/rfc2616#section-10.2.5).
## Update Server JSON Format
When an update is available, Tauri expects the following schema in response to the update request provided:
```json
{
"url": "https://mycompany.example.com/myapp/releases/myrelease.tar.gz",
"version": "0.0.1",
"notes": "Theses are some release notes",
"pub_date": "2020-09-18T12:29:53+01:00",
"signature": ""
}
```
The only required keys are "url" and "version", the others are optional.
"pub_date" if present must be formatted according to ISO 8601.
"signature" if present must be a valid signature generated with Tauri cli. See [Signing updates](#signing-updates).
## Update File JSON Format
The alternate update technique uses a plain JSON file meaning you can store your update metadata on S3, gist, or another static file store. Tauri will check against the name/version field and if the version is smaller than the current one and the platform is available, the update will be triggered. The format of this file is detailed below:
```json
{
"name":"v1.0.0",
"notes":"Test version",
"pub_date":"2020-06-22T19:25:57Z",
"platforms": {
"darwin": {
"signature":"",
"url":"https://github.com/lemarier/tauri-test/releases/download/v1.0.0/app.app.tar.gz"
},
"linux": {
"signature":"",
"url":"https://github.com/lemarier/tauri-test/releases/download/v1.0.0/app.AppImage.tar.gz"
},
"win64": {
"signature":"",
"url":"https://github.com/lemarier/tauri-test/releases/download/v1.0.0/app.x64.msi.zip"
}
}
}
```
# Bundler (Artifacts)
The Tauri bundler will automatically generate update artifacts if the updater is enabled in `tauri.conf.json`
If the bundler can locate your private and pubkey, your update artifacts will be automatically signed.
The signature can be found in the `sig` file. The signature can be uploaded to GitHub safely or made public as long as your private key is secure.
You can see how it's [bundled with the CI](https://github.com/tauri-apps/tauri/blob/5b6c7bb6ee3661f5a42917ce04a89d94f905c949/.github/workflows/artifacts-updater.yml#L44) and a [sample tauri.conf.json](https://github.com/tauri-apps/tauri/blob/5b6c7bb6ee3661f5a42917ce04a89d94f905c949/examples/updater/src-tauri/tauri.conf.json#L52)
## macOS
On MACOS we create a .tar.gz from the whole application. (.app)
```none
target/release/bundle
└── osx
└── app.app
└── app.app.tar.gz (update bundle)
└── app.app.tar.gz.sig (if signature enabled)
```
## Windows
On Windows we create a .zip from the MSI, when downloaded and validated, we run the MSI install.
```none
target/release
└── app.x64.msi
└── app.x64.msi.zip (update bundle)
└── app.x64.msi.zip.sig (if signature enabled)
```
## Linux
On Linux, we create a .tar.gz from the AppImage.
```none
target/release/bundle
└── appimage
└── app.AppImage
└── app.AppImage.tar.gz (update bundle)
└── app.AppImage.tar.gz.sig (if signature enabled)
```
# Signing updates
We offer a built-in signature to ensure your update is safe to be installed.
To sign your updates, you need two things.
The *Public-key* (pubkey) should be added inside your `tauri.conf.json` to validate the update archive before installing.
The *Private key* (privkey) is used to sign your update and should NEVER be shared with anyone. Also, if you lost this key, you'll NOT be able to publish a new update to the current user base (if pubkey is set in tauri.conf.json). It's important to save it at a safe place and you can always access it.
To generate your keys you need to use the Tauri cli.
```bash
tauri signer sign -g -w ~/.tauri/myapp.key
```
You have multiple options available
```bash
Tauri updates signer.
USAGE:
tauri signer sign [FLAGS] [OPTIONS]
FLAGS:
--force Overwrite private key even if it exists on the specified path
-g, --generate Generate keypair to sign files
-h, --help Prints help information
--no-password Set empty password for your private key
-V, --version Prints version information
OPTIONS:
-p, --password <password> Set private key password when signing
-k, --private-key <private-key> Load the private key from a string
-f, --private-key-path <private-key-path> Load the private key from a file
--sign-file <sign-file> Sign the specified file
-w, --write-keys <write-keys> Write private key to a file
```
***
Environment variables used to sign with the Tauri `bundler`:
If they are set, and `tauri.conf.json` expose the public key, the bundler will automatically generate and sign the updater artifacts.
`TAURI_PRIVATE_KEY` Path or String of your private key
`TAURI_KEY_PASSWORD` Your private key password (optional)

100
docs/guides/webdriver/ci.md
View File

@ -1,100 +0,0 @@
---
title: Continuous Integration
---
Utilizing Linux and some programs to create a fake display, it is possible to run [WebDriver] tests with
[`tauri-driver`] on your CI. The following example will use the [WebdriverIO] example we [previously built together] and
GitHub Actions.
This means the following assumptions:
1. The Tauri application is in the repository root and the binary builds when running `cargo build --release`.
2. The [WebDriverIO] test runner is in the `webdriver/webdriverio` directory and runs when `yarn test` is used in that
directory.
The following is a commented GitHub Actions workflow file at `.github/workflows/webdriver.yml`
```yaml
# run this action when the repository is pushed to
on: [ push ]
# the name of our workflow
name: WebDriver
jobs:
# a single job named test
test:
# the display name the test job
name: WebDriverIO Test Runner
# we want to run on the latest linux environment
runs-on: ubuntu-latest
# the steps our job runs **in order**
steps:
# checkout the code on the workflow runner
- uses: actions/checkout@v2
# install system dependencies that Tauri needs to compile on Linux.
# note the extra dependencies for `tauri-driver` to run which are `webkit2gtk-driver` and `xvfb`
- name: Tauri dependencies
run: >-
sudo apt-get update &&
sudo apt-get install -y
libgtk-3-dev
libgtksourceview-3.0-dev
webkit2gtk-4.0
libappindicator3-dev
webkit2gtk-driver
xvfb
# install the latest Rust stable
- name: Rust stable
uses: actions-rs/toolchain@v1
with:
toolchain: stable
# we run our rust tests before the webdriver tests to avoid testing a broken application
- name: Cargo test
uses: actions-rs/cargo@v1
with:
command: test
# build a release build of our application to be used during our WebdriverIO tests
- name: Cargo build
uses: actions-rs/cargo@v1
with:
command: build
args: --release
# install the latest stable node version at the time of writing
- name: Node v16
uses: actions/setup-node@v2
with:
node-version: 16.x
# install our Node.js dependencies with Yarn
- name: Yarn install
run: yarn install
working-directory: webdriver/webdriverio
# install the latest version of `tauri-driver`.
# note: the tauri-driver version is independent of any other Tauri versions
- name: Install tauri-driver
uses: actions-rs/cargo@v1
with:
command: install
args: tauri-driver
# run the WebdriverIO test suite.
# we run it through `xvfb-run` (the dependency we installed earlier) to have a fake
# display server which allows our application to run headless without any changes to the code
- name: WebdriverIO
run: xvfb-run yarn test
working-directory: webdriver/webdriverio
```
[WebDriver]: https://www.w3.org/TR/webdriver/
[`tauri-driver`]: https://crates.io/crates/tauri-driver
[WebdriverIO]: https://webdriver.io/
[previously built together]: example/webdriverio

256
docs/guides/webdriver/example/selenium.md
View File

@ -1,256 +0,0 @@
---
title: Selenium
---
import Alert from '@theme/Alert'
import Tabs from '@theme/Tabs'
import TabItem from '@theme/TabItem'
<Alert title="Example Application" type="info" icon="info-alt">
This [Selenium] guide expects you to have already gone through the [example Application setup] in order to follow
step-by-step. The general information may still be useful otherwise.
</Alert>
This WebDriver testing example will use [Selenium] and a popular Node.js testing suite. It is expected to already have
Node.js installed, along with `npm` or `yarn` although the [finished example project] uses `yarn`.
## Create a Directory for the Tests
Let's start off by creating a space in our project to write these tests. We are going to be using a nested directory for
this example project as we will later also go over other frameworks, but typically you will only need to use one. Create
the directory we will use with `mkdir -p webdriver/selenium`. The rest of this guide will assume you are inside the
`webdriver/selenium` directory.
## Initializing a Selenium Project
We will be using a pre-existing `package.json` to bootstrap this test suite because we have already chosen specific
dependencies to use and want to showcase a simple working solution. The bottom of this section has a collapsed
guide on how to set it up from scratch.
`package.json`:
```json
{
"name": "selenium",
"version": "1.0.0",
"private": true,
"scripts": {
"test": "mocha"
},
"dependencies": {
"chai": "^4.3.4",
"mocha": "^9.0.3",
"selenium-webdriver": "^4.0.0-beta.4"
}
}
```
We have a script which runs [Mocha] as a test framework exposed as the `test` command. We also have various dependencies
that we will be using to run the tests. [Mocha] as the testing framework, [Chai] as the assertion library, and
[`selenium-webdriver`] which is the Node.js [Selenium] package.
<details><summary>Click me if you want to see how to set a project up from scratch</summary>
If you wanted to install the dependencies from scratch, just run the following command.
<Tabs groupId="package-manager"
defaultValue="yarn"
values={[
{label: 'npm', value: 'npm'}, {label: 'Yarn', value: 'yarn'},
]}>
<TabItem value="npm">
```sh
npm install mocha chai selenium-webdriver
```
</TabItem>
<TabItem value="yarn">
```sh
yarn add mocha chai selenium-webdriver
```
</TabItem>
</Tabs>
I suggest also adding a `"test": "mocha"` item in the `package.json` `"scripts"` key so that running mocha can be called
simply with
<Tabs groupId="package-manager"
defaultValue="yarn"
values={[
{label: 'npm', value: 'npm'}, {label: 'Yarn', value: 'yarn'},
]}>
<TabItem value="npm">
```sh
npm test
```
</TabItem>
<TabItem value="yarn">
```sh
yarn test
```
</TabItem>
</Tabs>
</details>
## Testing
Unlike the [WebdriverIO Test Suite](webdriverio#config), Selenium does not come out of the box with a Test Suite and
leaves it up to the developer to build those out. We chose [Mocha] which is pretty neutral, and not related to WebDrivers
at all, so our script will need to do a bit of work to set up everything for us in the right order. [Mocha] expects a
testing file at `test/test.js` by default, so let's create that file now.
`test/test.js`:
```js
const os = require("os");
const path = require("path");
const { expect } = require("chai");
const { spawn, spawnSync } = require("child_process");
const { Builder, By, Capabilities } = require("selenium-webdriver");
// create the path to the expected application binary
const application = path.resolve(
__dirname,
"..",
"..",
"..",
"target",
"release",
"hello-tauri-webdriver"
);
// keep track of the webdriver instance we create
let driver;
// keep track of the tauri-driver process we start
let tauriDriver;
before(async function() {
// set timeout to 2 minutes to allow the program to build if it needs to
this.timeout(120000)
// ensure the program has been built
spawnSync("cargo", ["build", "--release"]);
// start tauri-driver
tauriDriver = spawn(
path.resolve(os.homedir(), ".cargo", "bin", "tauri-driver"),
[],
{ stdio: [null, process.stdout, process.stderr] }
);
const capabilities = new Capabilities();
capabilities.set("tauri:options", { application, args: ["app", "cli", "args"] });
capabilities.setBrowserName("wry");
// start the webdriver client
driver = await new Builder()
.withCapabilities(capabilities)
.usingServer("http://localhost:4444/")
.build();
});
after(async function() {
// stop the webdriver session
await driver.quit();
// kill the tauri-driver process
tauriDriver.kill();
});
describe("Hello Tauri", () => {
it("should be cordial", async () => {
const text = await driver.findElement(By.css("body > h1")).getText();
expect(text).to.match(/^[hH]ello/);
});
it("should be excited", async () => {
const text = await driver.findElement(By.css("body > h1")).getText();
expect(text).to.match(/!$/);
});
it("should be easy on the eyes", async () => {
// selenium returns color css values as rgb(r, g, b)
const text = await driver.findElement(By.css("body")).getCssValue("background-color");
const rgb = text.match(/^rgb\((?<r>\d+), (?<g>\d+), (?<b>\d+)\)$/).groups;
expect(rgb).to.have.all.keys('r','g','b');
const luma = 0.2126 * rgb.r + 0.7152 * rgb.g + 0.0722 * rgb.b ;
expect(luma).to.be.lessThan(100)
});
});
```
If you are familiar with JS testing frameworks, `describe`, `it`, and `expect` should look familiar. We also have
semi-complex `before()` and `after()` callbacks to setup and teardown mocha. Lines that are not the tests themselves
have comments explaining what the setup and teardown code is doing. If you were familiar with the Spec file from the
[WebdriverIO example](webdriverio#spec), you will notice a lot more code that isn't tests, as we have to set up a few
more WebDriver related items.
## Running the Test Suite
Now that we are all set up with our dependencies and our test script, lets run it!
<Tabs groupId="package-manager"
defaultValue="yarn"
values={[
{label: 'npm', value: 'npm'}, {label: 'Yarn', value: 'yarn'},
]}>
<TabItem value="npm">
```sh
npm test
```
</TabItem>
<TabItem value="yarn">
```sh
yarn test
```
</TabItem>
</Tabs>
We should see output the following output:
```text
➜ selenium git:(main) ✗ yarn test
yarn run v1.22.11
$ mocha
Hello Tauri
✔ should be cordial (120ms)
✔ should be excited
✔ should be easy on the eyes
3 passing (588ms)
Done in 0.93s.
```
We can see that our `Hello Tauri` sweet we created with `decribe` had all 3 items we created with `it` pass their
tests!
With [Selenium] and some hooking up to a test suite, we just enabled e2e testing without modifying our Tauri
application at all!
[Selenium]: https://selenium.dev/
[finished example project]: https://github.com/chippers/hello_tauri
[example Application setup]: setup
[Mocha]: https://mochajs.org/
[Chai]: https://www.chaijs.com/
[`selenium-webdriver`]: https://www.npmjs.com/package/selenium-webdriver

191
docs/guides/webdriver/example/setup.md
View File

@ -1,191 +0,0 @@
---
title: Setup Example
---
import HelloTauriWebdriver from '@site/static/img/webdriver/hello-tauri-webdriver.png'
This example application is going to solely focus on adding WebDriver testing to an already existing project. To have a
project to test on in the next two sections, we are going to set up an extremely minimal Tauri application for use in
our testing. We will not use the Tauri CLI, any frontend dependencies or build steps, and not be bundling the
application afterwards. This is to showcase exactly a minimal suite to show off adding WebDriver testing to an existing
application.
If you just want to see the finished example project that utilizes what will be shown in this example guide, then you
can see https://github.com/chippers/hello_tauri.
## Initializing a Cargo Project
We want to create a new binary Cargo project to house this example application. We can easily do this from the command
line with `cargo new hello-tauri-webdriver --bin` which will scaffold a minimal binary Cargo project for us. This
directory will serve as the working directory for the rest of this guide, so make sure commands you run are inside this
new `hello-tauri-webdriver/` directory.
## Creating a Minimal Frontend
We will create a minimal HTML file to act as the frontend to our example application. We will also be using a few things
from this frontend later during our WebDriver tests.
First, let's create our Tauri `distDir` that we know we will need once building the Tauri portion of the application.
`mkdir dist` should create a new directory called `dist/` in which we will be placing the following `index.html` file.
`dist/index.html`:
```html
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<title>Hello Tauri!</title>
<style>
body {
/* Add a nice colorscheme */
background-color: #222831;
color: #ececec;
/* Make the body the exact size of the window */
margin: 0;
height: 100vh;
width: 100vw;
/* Vertically and horizontally center children of the body tag */
display: flex;
justify-content: center;
align-items: center;
}
</style>
</head>
<body>
<h1>Hello, Tauri!</h1>
</body>
</html>
```
## Adding Tauri to the Cargo Project
Next, we will add some necessary items to make our Cargo project into a Tauri project. First, is adding the dependencies
to the Cargo Manifest (`Cargo.toml`) so that Cargo knows to pull in our dependencies while building.
`Cargo.toml`:
```toml
[package]
name = "hello-tauri-webdriver"
version = "0.1.0"
edition = "2021"
rust-version = "1.56"
# Needed to set up some things for Tauri at build time
[build-dependencies]
tauri-build = "1.0.0-beta.4"
# The actual Tauri dependency, along with `custom-protocol` to serve the pages.
[dependencies]
tauri = { version = "1.0.0-beta.6", features = ["custom-protocol"] }
# Make --release build a binary that is small (opt-level = "s") and fast (lto = true).
# This is completely optional, but shows that testing the application as close to the
# typical release settings is possible. Note: this will slow down compilation.
[profile.release]
incremental = false
codegen-units = 1
panic = "abort"
opt-level = "s"
lto = true
```
As you may have noticed, we added a `[build-dependency]`. To use the build dependency, we must use it from a build
script. We will create one now at `build.rs`.
`build.rs`:
```rust
fn main() {
// Only watch the `dist/` directory for recompiling, preventing unnecessary
// changes when we change files in other project subdirectories.
println!("cargo:rerun-if-changed=dist");
// Run the Tauri build-time helpers
tauri_build::build()
}
```
With all that setup, our Cargo Project now knows how to pull in and build our Tauri dependencies. Let's finish making
this minimal example a Tauri application by setting up Tauri in the actual project code. We will be editing
the `src/main.rs`
file to add this Tauri functionality.
`src/main.rs`:
```rust
fn main() {
tauri::Builder::default()
.run(tauri::generate_context!())
.expect("unable to run Tauri application");
}
```
Pretty simple, right?
## Tauri Configuration
We are going to need 2 things to successfully build the application. First, we need an icon file. You can use any PNG
for this next part and copy it into `icon.png`. Typically, this will be provided as part of the scaffolding when you use
the Tauri CLI to create a project. To get the default Tauri icon, we can download the icon used by the Hello Tauri
example repository with the
command `curl -L "https://github.com/chippers/hello_tauri/raw/main/icon.png" --output icon.png`.
The second thing we will need is a `tauri.conf.json` to specify some important configuration values to Tauri. Again,
this would typically come from the `tauri init` scaffolding command, but we will be creating our own minimal config
here.
`tauri.conf.json`:
```json
{
"build": {
"distDir": "dist"
},
"tauri": {
"bundle": {
"identifier": "studio.tauri.hello_tauri_webdriver",
"icon": [
"icon.png"
]
},
"allowlist": {
"all": false
},
"windows": [
{
"width": 800,
"height": 600,
"resizable": true,
"fullscreen": false
}
]
}
}
```
I'll go over some of these. You can see the `dist/` directory we created earlier specified as the `distDir` property. We
set a bundle identifier so that the built application has a unique id, along with setting the `icon.png` as the only
icon. We aren't using any Tauri apis or features, so we just disable all them in `allowlist` by setting `"all": false`.
The window values just sets a single window to be created with some reasonable default values.
At this point, we have a basic Hello World application that when ran, should display a simple greeting.
## Running the Example Application
To make sure we did it right, let's build this application! We will run this as a `--release` application because we
will also run our WebDriver tests with a release profile. Run `cargo run --release` and after some compiling we should
see the following application pop up.
<div style={{textAlign: 'center'}}>
<img src={HelloTauriWebdriver}/>
</div>
_Note: If you are modifying the application and want to use the Devtools, then run it without `--release` and "Inspect
Element" should be available in the right click menu._
We should now be ready to start testing this application with some WebDriver frameworks. This guide will go over both
[WebdriverIO](webdriverio) and [Selenium](selenium) in that order.

276
docs/guides/webdriver/example/webdriverio.md
View File

@ -1,276 +0,0 @@
---
title: WebdriverIO
---
import Alert from '@theme/Alert'
import Tabs from '@theme/Tabs'
import TabItem from '@theme/TabItem'
<Alert title="Example Application" type="info" icon="info-alt">
This [WebdriverIO] guide expects you to have already gone through the [example Application setup] in order to follow
step-by-step. The general information may still be useful otherwise.
</Alert>
This WebDriver testing example will use [WebdriverIO] and its testing suite. It is expected to already have Node.js
installed, along with `npm` or `yarn` although the [finished example project] uses `yarn`.
## Create a Directory for the Tests
Let's start off by creating a space in our project to write these tests. We are going to be using a nested directory for
this example project as we will later also go over other frameworks, but typically you will only need to use one. Create
the directory we will use with `mkdir -p webdriver/webdriverio`. The rest of this guide will assume you are inside the
`webdriver/webdriverio` directory.
## Initializing a WebdriverIO Project
We will be using a pre-existing `package.json` to bootstrap this test suite because we have already chosen specific
[WebdriverIO] config options and want to showcase a simple working solution. The bottom of this section has a collapsed
guide on how to set it up from scratch.
`package.json`:
```json
{
"name": "webdriverio",
"version": "1.0.0",
"private": true,
"scripts": {
"test": "wdio run wdio.conf.js"
},
"dependencies": {
"@wdio/cli": "^7.9.1"
},
"devDependencies": {
"@wdio/local-runner": "^7.9.1",
"@wdio/mocha-framework": "^7.9.1",
"@wdio/spec-reporter": "^7.9.0"
}
}
```
We have a script which runs a [WebdriverIO] config as a test suite exposed as the `test` command. We also have various
dependencies that were added by the `@wdio/cli` command when we first set it up. In short, these dependencies are for
the most simple setup using a local WebDriver runner, [Mocha] as the test framework, and a simple Spec Reporter.
<details><summary>Click me if you want to see how to set a project up from scratch</summary>
The CLI is interactive, and you may choose the tools to work with yourself. Note that you will likely diverge from
the rest of the guide, and need to set up the differences yourself.
Let's add the [WebdriverIO] CLI to this npm project.
<Tabs groupId="package-manager"
defaultValue="yarn"
values={[
{label: 'npm', value: 'npm'}, {label: 'Yarn', value: 'yarn'},
]}>
<TabItem value="npm">
```sh
npm install @wdio/cli
```
</TabItem>
<TabItem value="yarn">
```sh
yarn add @wdio/cli
```
</TabItem>
</Tabs>
To then run the interactive config command to set up a [WebdriverIO] test suite, you can then run:
<Tabs groupId="package-manager"
defaultValue="yarn"
values={[
{label: 'npm', value: 'npm'}, {label: 'Yarn', value: 'yarn'},
]}>
<TabItem value="npm">
```sh
npx wdio config
```
</TabItem>
<TabItem value="yarn">
```sh
yarn wdio config
```
</TabItem>
</Tabs>
</details>
## Config
You may have noticed that the `test` script in our `package.json` mentions a file `wdio.conf.js`. That's the [WebdriverIO]
config file which controls most aspects of our testing suite.
`wdio.conf.js`:
```js
const os = require("os");
const path = require("path");
const { spawn, spawnSync } = require("child_process");
// keep track of the `tauri-driver` child process
let tauriDriver;
exports.config = {
specs: ["./test/specs/**/*.js"],
maxInstances: 1,
capabilities: [
{
maxInstances: 1,
"tauri:options": {
application: "../../target/release/hello-tauri-webdriver",
args: ["app", "cli", "args"]
},
},
],
reporters: ["spec"],
framework: "mocha",
mochaOpts: {
ui: "bdd",
timeout: 60000,
},
// ensure the rust project is built since we expect this binary to exist for the webdriver sessions
onPrepare: () => spawnSync("cargo", ["build", "--release"]),
// ensure we are running `tauri-driver` before the session starts so that we can proxy the webdriver requests
beforeSession: () =>
(tauriDriver = spawn(
path.resolve(os.homedir(), ".cargo", "bin", "tauri-driver"),
[],
{ stdio: [null, process.stdout, process.stderr] }
)),
// clean up the `tauri-driver` process we spawned at the start of the session
afterSession: () => tauriDriver.kill(),
};
```
If you are interested in the properties on `exports.config` object, then I [suggest reading the documentation] for it.
For non-WDIO specific items, there are comments explaining why we are running commands in `onPrepare`, `beforeSession`,
and `afterSession`. We also have our specs set to `"./test/specs/**/*.js"`, so let's create a spec now.
## Spec
A spec contains the code that is testing your actual application. The test runner will load these specs and automatically
run them as it sees fit. Let's create our spec now in the directory we specified.
`test/specs/example.e2e.js`:
```js
// calculates the luma from a hex color `#abcdef`
function luma(hex) {
if (hex.startsWith("#")) {
hex = hex.substring(1);
}
const rgb = parseInt(hex, 16);
const r = (rgb >> 16) & 0xff;
const g = (rgb >> 8) & 0xff;
const b = (rgb >> 0) & 0xff;
return 0.2126 * r + 0.7152 * g + 0.0722 * b;
}
describe("Hello Tauri", () => {
it("should be cordial", async () => {
const header = await $("body > h1");
const text = await header.getText();
expect(text).toMatch(/^[hH]ello/);
});
it("should be excited", async () => {
const header = await $("body > h1");
const text = await header.getText();
expect(text).toMatch(/!$/);
});
it("should be easy on the eyes", async () => {
const body = await $("body");
const backgroundColor = await body.getCSSProperty("background-color");
expect(luma(backgroundColor.parsed.hex)).toBeLessThan(100);
});
});
```
The `luma` function on top is just a helper function for one of our tests and is not related to the actual testing of
the application. If you are familiar with other testing frameworks, you may notice similar functions being exposed that
are used such as `describe`, `it`, and `expect`. The other APIs, such as items like `$` and the methods it exposes is
covered by the [WebdriverIO API docs](https://webdriver.io/docs/api).
## Running the Test Suite
Now that we are all set up with a config and a spec, let's run it!
<Tabs groupId="package-manager"
defaultValue="yarn"
values={[
{label: 'npm', value: 'npm'}, {label: 'Yarn', value: 'yarn'},
]}>
<TabItem value="npm">
```sh
npm test
```
</TabItem>
<TabItem value="yarn">
```sh
yarn test
```
</TabItem>
</Tabs>
We should see output the following output:
```text
➜ webdriverio git:(main) ✗ yarn test
yarn run v1.22.11
$ wdio run wdio.conf.js
Execution of 1 workers started at 2021-08-17T08:06:10.279Z
[0-0] RUNNING in undefined - /test/specs/example.e2e.js
[0-0] PASSED in undefined - /test/specs/example.e2e.js
"spec" Reporter:
------------------------------------------------------------------
[wry 0.12.1 linux #0-0] Running: wry (v0.12.1) on linux
[wry 0.12.1 linux #0-0] Session ID: 81e0107b-4d38-4eed-9b10-ee80ca47bb83
[wry 0.12.1 linux #0-0]
[wry 0.12.1 linux #0-0] » /test/specs/example.e2e.js
[wry 0.12.1 linux #0-0] Hello Tauri
[wry 0.12.1 linux #0-0] ✓ should be cordial
[wry 0.12.1 linux #0-0] ✓ should be excited
[wry 0.12.1 linux #0-0] ✓ should be easy on the eyes
[wry 0.12.1 linux #0-0]
[wry 0.12.1 linux #0-0] 3 passing (244ms)
Spec Files: 1 passed, 1 total (100% completed) in 00:00:01
Done in 1.98s.
```
We see the Spec Reporter tell us that all 3 tests from the `test/specs/example.e2e.js` file, along with the final report
`Spec Files: 1 passed, 1 total (100% completed) in 00:00:01`.
Using the [WebdriverIO] test suite, we just easily enabled e2e testing for our Tauri application from just a few lines
of configuration and a single command to run it! Even better, we didn't have to modify the application at all.
[WebdriverIO]: https://webdriver.io/
[finished example project]: https://github.com/chippers/hello_tauri
[example Application setup]: setup
[Mocha]: https://mochajs.org/
[suggest reading the documentation]: https://webdriver.io/docs/configurationfile

56
docs/guides/webdriver/introduction.md
View File

@ -1,56 +0,0 @@
---
title: Introduction
---
import Alert from '@theme/Alert'
<Alert title="Currently in pre-alpha" type="info" icon="info-alt">
Webdriver support for Tauri is still in pre-alpha. Tooling that is dedicated to it such as [tauri-driver] is still in
active development and may change as necessary over time. Additionally, only Windows and Linux are currently supported.
</Alert>
[WebDriver] is a standardized interface to interact with web documents that is primarily intended for automated testing.
Tauri supports the [WebDriver] interface by leveraging the native platform's [WebDriver] server underneath a
cross-platform wrapper [`tauri-driver`].
## System Dependencies
Install the latest [`tauri-driver`] or update an existing installation by running:
```sh
cargo install tauri-driver
```
Because we currently utilize the platform's native [WebDriver] server, there are some requirements for running
[`tauri-driver`] on supported platforms. Platform support is currently limited to Linux and Windows.
### Linux
We use `WebKitWebDriver` on linux platforms. Check if this binary exists already (command `which WebKitWebDriver`) as
some distributions bundle it with the regular webkit package. Other platforms may have a separate package for them such
as `webkit2gtk-driver` on Debian based distributions.
### Windows
Make sure to grab the version of [Microsoft Edge Driver] that matches your Windows' Edge version that the application is
being built and tested on. On up-to-date Window installs, this should almost always be the latest stable version. If the
two versions do not match, you may experience your WebDriver testing suite hanging while trying to connect.
The download contains a binary called `msedgedriver.exe`. [`tauri-driver`] looks for that binary in the `$PATH` so make
sure it's either available on the path or use the `--native-driver` option on [`tauri-driver`]. On Windows CI machines,
you may want to download this automatically as part of the CI setup process to ensure the Edge and Edge Driver versions
stay in sync. A guide on how to do this may be added at a later date.
## Example Application
The [next section](example/setup) of the guide will show step-by-step how to create a minimal example application that
is tested with WebDriver.
If you prefer to just see the result of the guide and look over a finished minimal codebase that utilizes it then you
can look at https://github.com/chippers/hello_tauri. That example also comes with a CI script to test with GitHub
actions, but you may still be interested in the [WebDriver CI](ci) guide as it explains the concept a bit more.
[WebDriver]: https://www.w3.org/TR/webdriver/
[`tauri-driver`]: https://crates.io/crates/tauri-driver
[tauri-driver]: https://crates.io/crates/tauri-driver
[Microsoft Edge Driver]: https://developer.microsoft.com/en-us/microsoft-edge/tools/webdriver/

89
docs/guides/window-customization.md
View File

@ -1,89 +0,0 @@
---
title: Window Customization
---
Tauri provides lots of options for customizing the look and feel of your app's window. You can create custom titlebars, have transparent windows, enforce size constraints, and more.
## Configuration
There are three ways to change the window configuration:
- [Through tauri.conf.json](https://tauri.studio/en/docs/api/config/#tauri.windows)
- [Through the JS API](https://tauri.studio/en/docs/api/js/classes/window.windowmanager)
- [Through the Window in Rust](https://tauri.studio/en/docs/api/rust/tauri/window/struct.window)
## Creating a Custom Titlebar
A common use of these window features is creating a custom titlebar. This short tutorial will guide you through that process.
### CSS
You'll need to add some CSS for the titlebar to keep it at the top of the screen and style the buttons:
```css
.titlebar {
height: 30px;
background: #329ea3;
user-select: none;
display: flex;
justify-content: flex-end;
position: fixed;
top: 0;
left: 0;
right: 0;
}
.titlebar-button {
display: inline-flex;
justify-content: center;
align-items: center;
width: 30px;
height: 30px;
}
.titlebar-button:hover {
background: #5bbec3;
}
```
### HTML
Now, you'll need to add the HTML for the titlebar. Put this at the top of your `<body>` tag:
```html
<div data-tauri-drag-region class="titlebar">
<div class="titlebar-button" id="titlebar-minimize">
<img
src="https://api.iconify.design/mdi:window-minimize.svg"
alt="minimize"
/>
</div>
<div class="titlebar-button" id="titlebar-maximize">
<img
src="https://api.iconify.design/mdi:window-maximize.svg"
alt="maximize"
/>
</div>
<div class="titlebar-button" id="titlebar-close">
<img src="https://api.iconify.design/mdi:close.svg" alt="close" />
</div>
</div>
```
Note that you may need to move the rest of your content down so that the titlebar doesn't cover it.
### JS
Finally, you'll need to make the buttons work:
```js
import { appWindow } from '@tauri-apps/api/window'
document
.getElementById('titlebar-minimize')
.addEventListener('click', () => appWindow.minimize())
document
.getElementById('titlebar-maximize')
.addEventListener('click', () => appWindow.toggleMaximize())
document
.getElementById('titlebar-close')
.addEventListener('click', () => appWindow.close())
```

110
docs/sidebar.json
View File

@ -1,110 +0,0 @@
[
{
"label": "Get started",
"type": "category",
"items": [
"get-started/intro",
"get-started/setup-linux",
"get-started/setup-macos",
"get-started/setup-windows"
]
},
{
"label": "Development",
"type": "category",
"items": [
"development/intro",
"development/integration",
"development/development",
"development/debugging",
"development/ci-cd",
"development/cross-platform",
"development/publishing",
"development/updating"
]
},
{
"label": "Guides",
"type": "category",
"items": [
{
"label": "Patterns",
"type": "category",
"items": [
"guides/patterns/about-patterns",
"guides/patterns/hermit",
"guides/patterns/bridge",
"guides/patterns/cloudish",
"guides/patterns/cloudbridge",
"guides/patterns/lockdown",
"guides/patterns/multiwin",
"guides/patterns/glui"
]
},
{
"label": "Bundler",
"type": "category",
"items": [
"guides/bundler/introduction",
"guides/bundler/anti-bloat",
"guides/bundler/sidecar",
"guides/bundler/debian",
"guides/bundler/sign-macos",
"guides/bundler/sign-windows"
]
},
"guides/cli",
"guides/command",
"guides/events",
"guides/plugin",
"guides/updater",
"guides/icons",
"guides/splashscreen",
"guides/window-customization",
"guides/menu",
"guides/system-tray",
{
"label": "WebDriver Testing",
"type": "category",
"items": [
"guides/webdriver/introduction",
{
"label": "Example Application",
"type": "category",
"items": [
"guides/webdriver/example/setup",
"guides/webdriver/example/webdriverio",
"guides/webdriver/example/selenium"
]
},
"guides/webdriver/ci"
]
},
"guides/migration",
"guides/contributor-guide"
]
},
{
"label": "Tips",
"type": "category",
"items": []
},
{
"label": "API",
"type": "category",
"items": [
"api/config",
"api/cli",
{
"label": "Rust",
"type": "category",
"items": []
},
{
"label": "JavaScript",
"type": "category",
"items": []
}
]
}
]