tauri-apps/tauri
1
1
Fork 0
mirror of https://github.com/tauri-apps/tauri.git synced 2024-12-01 03:02:28 +03:00
Code Issues Packages Projects Releases Wiki Activity

feat(docs): Added version-bound docs (#1676)

Browse Source
This commit is contained in:
Laegel 2021-06-02 13:55:07 +02:00 committed by GitHub
parent c021968eb8
commit 37db639a65
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
41 changed files with 3800 additions and 9 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

71
.github/workflows/covector-version-or-publish.yml vendored
View File

@ -58,6 +58,7 @@ jobs:
if: needs.version-or-publish.outputs.successfulPublish == 'true'
runs-on: ubuntu-latest
steps:
# Setup
- name: checkout tauri
uses: actions/checkout@v2
with:
@ -67,28 +68,88 @@ jobs:
with:
repository: tauri-apps/tauri-docs
path: tauri-docs
- name: checkout tauri-search-bot
uses: actions/checkout@v2
with:
repository: tauri-apps/tauri-search-bot
path: tauri-search-bot
- name: install webkit2gtk
run: |
sudo apt-get update
sudo apt-get install -y libgtk-3-dev libgtksourceview-3.0-dev webkit2gtk-4.0 libappindicator3-dev
# Rust
- name: generate rust docs
working-directory: ./tauri/core/tauri
run: cargo doc --no-deps
- name: run rustdocusaurus
uses: tauri-apps/rustdocusaurus/github-action@v1
uses: tauri-apps/rustdocusaurus/github-action@v1.0.3
with:
originPath: ./tauri/target/doc/
targetPath: ./tauri-docs/docs/en/api/rust/
sidebarPath: ./tauri-docs/sidebars.json
linksRoot: /docs/api/rust/
sidebarPath: ./tauri-docs/sidebars/rustdoc.json
linksRoot: ""
cratesToProcess: "tauri"
# TypeScript
- name: run typedocusaurus
uses: tauri-apps/typedocusaurus@v1
with:
originPath: ./tauri/tooling/api/
sidebarFile: sidebars.json
targetPath: en/api/js
sidebarFile: ./tauri-docs/sidebars/typedoc.json
targetPath: ./tauri-docs/en/api/js/
docusaurusPath: ./tauri-docs/
# Moving docs for Indexation
- name: copy docs
working-directory: ./tauri
run: mv docs/sidebar.json ../tauri-docs/sidebars/core.json && cp -r docs ../tauri-docs/docs/en
# Indexing
- name: meilisearch indexation
uses: tauri-apps/docusaurus-meilisearch-indexer@v1
with:
- version: ${{ github.event.release.tag_name }}
- docusaurusPath: ./tauri-docs
- host: https://search.tauri.studio
- apiKey: ${{ secrets.MEILISEARCH_APIKEY }}
- docs: "Getting started,Usage,API"
# Applying Version
- name: set docs' Tauri version
working-directory: ./tauri-docs
run: echo ${{ github.event.release.tag_name }} > version.txt
- name: set bot's Tauri version
working-directory: ./tauri-search-bot
uses: iamsauravsharma/create-dotenv@v1.1.0
env:
ENV_KEY_DISCORD_BOT_SECRET: ${{ secrets.DISCORD_BOT_SECRET }}
ENV_KEY_PREFIX: !
ENV_KEY_SITE: tauri.studio
ENV_KEY_ICON: https://i.imgur.com/UzDERvw.png
ENV_KEY_LIMIT: 5
ENV_KEY_SEARCH_INDEX: ${{ github.event.release.tag_name }}
ENV_KEY_MEILISEARCH_PUBLIC_KEY: ea0105f56bb5a2111ed28c7a0c637fc0bed07273f571dc7cb1f73900e44f8e7f
# Bot Deployment
- name: scp bot
working-directory: ./tauri-search-bot
uses: appleboy/scp-action@master
with:
host: ${{ secrets.DISCORD_BOT_HOST }}
username: ${{ secrets.DISCORD_BOT_SSH_USER }}
key: ${{ secrets.DISCORD_BOT_SSH_KEY }}
source: "."
target: "~/tauri-search-bot"
- name: restart the bot
uses: appleboy/ssh-action@master
with:
host: ${{ secrets.DISCORD_BOT_HOST }}
username: ${{ secrets.DISCORD_BOT_SSH_USER }}
key: ${{ secrets.DISCORD_BOT_SSH_KEY }}
script: cd ~/tauri-search-bot && yarn && forever stopall && forever start ./src/index.js
# tauri-docs PR
- name: git config
run: |
git config --global user.name "${{ github.event.pusher.name }}"

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

@ -20,6 +20,7 @@ jobs:
update-docs:
runs-on: ubuntu-latest
steps:
# Setup
- name: checkout tauri
uses: actions/checkout@v2
with:
@ -29,10 +30,17 @@ jobs:
with:
repository: tauri-apps/tauri-docs
path: tauri-docs
- name: checkout tauri-search-bot
uses: actions/checkout@v2
with:
repository: tauri-apps/tauri-search-bot
path: tauri-search-bot
- name: install webkit2gtk
run: |
sudo apt-get update
sudo apt-get install -y libgtk-3-dev libgtksourceview-3.0-dev webkit2gtk-4.0 libappindicator3-dev
# Rust
- name: generate rust docs
working-directory: ./tauri/core/tauri
run: cargo doc --no-deps
@ -41,16 +49,69 @@ jobs:
with:
originPath: ./tauri/target/doc/
targetPath: ./tauri-docs/docs/en/api/rust/
sidebarPath: ./tauri-docs/sidebars.json
linksRoot: /docs/api/rust/
sidebarPath: ./tauri-docs/sidebars/rustdoc.json
linksRoot: ""
cratesToProcess: "tauri"
# TypeScript
- name: run typedocusaurus
uses: tauri-apps/typedocusaurus@v1
with:
originPath: ./tauri/tooling/api/
sidebarFile: sidebars.json
targetPath: en/api/js
sidebarFile: ./tauri-docs/sidebars/typedoc.json
targetPath: ./tauri-docs/en/api/js/
docusaurusPath: ./tauri-docs/
# Moving docs for Indexation
- name: copy docs
working-directory: ./tauri
run: mv docs/sidebar.json ../tauri-docs/sidebars/core.json && cp -r docs ../tauri-docs/docs/en
# Indexing
- name: meilisearch indexation
uses: tauri-apps/docusaurus-meilisearch-indexer@v1
with:
- version: ${{ github.event.release.tag_name }}
- docusaurusPath: ./tauri-docs
- host: https://search.tauri.studio
- apiKey: ${{ secrets.MEILISEARCH_APIKEY }}
- docs: "Getting started,Usage,API"
# Applying Version
- name: set docs' Tauri version
working-directory: ./tauri-docs
run: echo ${{ github.event.release.tag_name }} > version.txt
- name: set bot's Tauri version
working-directory: ./tauri-search-bot
uses: iamsauravsharma/create-dotenv@v1.1.0
env:
ENV_KEY_DISCORD_BOT_SECRET: ${{ secrets.DISCORD_BOT_SECRET }}
ENV_KEY_PREFIX: !
ENV_KEY_SITE: tauri.studio
ENV_KEY_ICON: https://i.imgur.com/UzDERvw.png
ENV_KEY_LIMIT: 5
ENV_KEY_SEARCH_INDEX: ${{ github.event.release.tag_name }}
ENV_KEY_MEILISEARCH_PUBLIC_KEY: ea0105f56bb5a2111ed28c7a0c637fc0bed07273f571dc7cb1f73900e44f8e7f
# Bot Deployment
- name: scp bot
working-directory: ./tauri-search-bot
uses: appleboy/scp-action@master
with:
host: ${{ secrets.DISCORD_BOT_HOST }}
username: ${{ secrets.DISCORD_BOT_SSH_USER }}
key: ${{ secrets.DISCORD_BOT_SSH_KEY }}
source: "."
target: "~/tauri-search-bot"
- name: restart the bot
uses: appleboy/ssh-action@master
with:
host: ${{ secrets.DISCORD_BOT_HOST }}
username: ${{ secrets.DISCORD_BOT_SSH_USER }}
key: ${{ secrets.DISCORD_BOT_SSH_KEY }}
script: cd ~/tauri-search-bot && yarn && forever stopall && forever start ./src/index.js
# tauri-docs PR
- name: git config
run: |
git config --global user.name "${{ github.event.inputs.gitName }}"

136
docs/api/cli.md Normal file
View File

@ -0,0 +1,136 @@
---
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" />
```
Description
Inits the Tauri template. If Tauri cannot find the src-tauri/tauri.conf.json
it will create one.
Usage
$ tauri init
Options
--help, -h Displays this message
--force, -f Force init to overwrite [conf|template|all]
--log, -l Logging [boolean]
--directory, -d Set target directory for init
--tauriPath, -t Path of the Tauri project to use (relative to the cwd)
```
## `dev`
<Command name="dev" />
```
Description
Tauri dev.
Usage
$ tauri dev
Options
--help, -h Displays this message
```
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" />
```
Description
Tauri build.
Usage
$ tauri build
Options
--help, -h Displays this message
--debug, -d Build a tauri app with debugging
```
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
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]
```
This command will generate a set of icons, based on the source icon you've entered.
## `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/usage/development/integration).

363
docs/api/config.md Normal file
View File

@ -0,0 +1,363 @@
---
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.
It's composed of the following properties:
## `build`
<Properties anchorRoot="build" rows={[
{property: "distDir", type: "string", description: `The path—either absolute or relative—to the production-ready webpage/webapp directory 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—either absolute or relative—to a folder 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.`},
{property: "beforeBuildCommand", optional: true, type: "string", description: `A command to run before starting Tauri in build mode.`},
{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."}
]}/>
```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: "name", optional: true, type: "string", description: `Application binary name. Converted to snake-case on Linux.` },
{ property: "version", optional: true, type: "string", description: `Application version.` }
]}/>
## `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/usage/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/usage/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: "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: "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: "path", optional: true, type: "boolean", description: `Resolve system paths.` },
]}/>
},
{
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: "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: "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: "minHeight", type: "number", description: `The minimum 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: "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.` },
]}/>
</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: http: https: 'unsafe-eval' 'unsafe-inline'"
}
}
```

36
docs/getting-started/intro.md Normal file
View File

@ -0,0 +1,36 @@
---
title: Introduction
---
import OSList from '@theme/OSList'
Welcome to Tauri! 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/getting-started/setup-linux'},
macos: { title: 'macOS Setup', link: '/docs/getting-started/setup-macos'},
windows: { title: 'Windows Setup', link: '/docs/getting-started/setup-windows'}
}} />
After that, you'll be ready to [add Tauri to your project!](/docs/usage/development/integration)

137
docs/getting-started/setup-linux.md Normal file
View File

@ -0,0 +1,137 @@
---
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 \
appmenu-gtk3-module \
libgtk-3-dev \
squashfs-tools
```
</TabItem>
<TabItem value="arch">
```sh
$ sudo pacman -Syy && sudo pacman -S webkit2gtk \
base-devel \
curl \
wget \
openssl \
appmenu-gtk-module \
gtk3 \
squashfs-tools
```
</TabItem>
<TabItem value="fedora">
```sh
$ sudo dnf check-update && sudo dnf install webkit2gtk3-devel.x86_64 \
openssl-devel \
curl \
wget \
squashfs-tools \
&& sudo dnf group install "C Development Tools and Libraries"
```
</TabItem>
</Tabs>
## 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/getting-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/usage/development/integration).

79
docs/getting-started/setup-macos.md Normal file
View File

@ -0,0 +1,79 @@
---
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/getting-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/usage/development/integration).

66
docs/getting-started/setup-windows.md Normal file
View File

@ -0,0 +1,66 @@
---
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/getting-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.
<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/getting-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
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).
## Continue
Now that you have set up the Windows-specific dependencies for Tauri, learn how to [add Tauri to your project](/docs/usage/development/integration).

109
docs/sidebar.json Normal file
View File

@ -0,0 +1,109 @@
[
{
"label": "Getting started",
"type": "category",
"items": [
"getting-started/intro",
"getting-started/setup-linux",
"getting-started/setup-macos",
"getting-started/setup-windows"
]
},
{
"label": "Usage",
"type": "category",
"items": [
"usage/intro",
{
"label": "Development",
"type": "category",
"items": [
"usage/development/integration",
"usage/development/development",
"usage/development/debugging",
"usage/development/publishing",
"usage/development/updating"
]
},
{
"label": "Patterns",
"type": "category",
"items": [
"usage/patterns/about-patterns",
"usage/patterns/hermit",
"usage/patterns/bridge",
"usage/patterns/cloudish",
"usage/patterns/cloudbridge",
"usage/patterns/lockdown",
"usage/patterns/multiwin",
"usage/patterns/glui"
]
},
{
"label": "Guides",
"type": "category",
"items": [
"usage/guides/migration",
{
"label": "Bundler",
"type": "category",
"items": [
"usage/guides/bundler/introduction",
"usage/guides/bundler/anti-bloat",
"usage/guides/bundler/sidecar",
"usage/guides/bundler/debian"
]
},
"usage/guides/cli",
"usage/guides/command",
"usage/guides/events",
"usage/guides/plugin",
"usage/guides/updater",
{
"label": "Visual",
"type": "category",
"items": [
"usage/guides/visual/icons",
"usage/guides/visual/splashscreen",
"usage/guides/visual/window-customization",
"usage/guides/visual/menu",
"usage/guides/visual/system-tray"
]
}
]
},
{
"label": "CI/CD",
"type": "category",
"items": [
"usage/ci-cd/workflow",
"usage/ci-cd/cross-platform"
]
},
"usage/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": []
}
]
}
]

5
docs/usage/ci-cd/cross-platform.md Normal file
View File

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

5
docs/usage/ci-cd/signing-macos.md Normal file
View File

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

80
docs/usage/ci-cd/workflow.md Normal file
View File

@ -0,0 +1,80 @@
---
id: workflow
title: Workflow
---
## 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.

52
docs/usage/contributor-guide.md Normal file
View File

@ -0,0 +1,52 @@
---
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" ]
```

61
docs/usage/development/debugging.md Normal file
View File

@ -0,0 +1,61 @@
---
title: App Debugging
sidebar_label: 'App Debugging (3/4)'
---
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.

27
docs/usage/development/development.md Normal file
View File

@ -0,0 +1,27 @@
---
title: App Development
sidebar_label: 'App Development (2/4)'
---
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.toml" to git because you want it to be deterministic. You SHOULD NOT commit the "src-tauri/target" folder or any of its contents.
</Alert>

126
docs/usage/development/integration.md Normal file
View File

@ -0,0 +1,126 @@
---
title: Tauri Integration
sidebar_label: 'Tauri Integration (1/4)'
---
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/getting-started/intro#setting-up-your-environment"> setup page for your operating system</a>.
</Alert>
### 1. 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"
}
}
```
### 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: http: https: '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/usage/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).

23
docs/usage/development/publishing.md Normal file
View File

@ -0,0 +1,23 @@
---
title: App Publishing
sidebar_label: 'App Publishing (4/4)'
---
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.

42
docs/usage/development/updating.md Normal file
View File

@ -0,0 +1,42 @@
---
title: Updating
---
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.

82
docs/usage/guides/bundler/anti-bloat.md Normal file
View File

@ -0,0 +1,82 @@
---
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 and squeeze some more size out of the resulting binary. `"s"` and `"z"` can sometimes be smaller than the other, so test it with your own application!
We've seen better 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 entails.
</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 remove some additional 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 sized 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.
### 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 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/usage/guides/bundler/debian.md Normal file
View File

@ -0,0 +1,34 @@
---
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/usage/guides/bundler/introduction.md Normal file
View File

@ -0,0 +1,11 @@
---
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

39
docs/usage/guides/bundler/sidecar.md Normal file
View File

@ -0,0 +1,39 @@
---
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` namespace in your `tauri.conf.json`.
See more about tauri.conf.json configuration <a href="/docs/api/config#build">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/bin1", "relative/path/to/bin2"]
}
}
}
```
This way, you may [execute commands with Rust](https://doc.rust-lang.org/std/process/struct.Command.html) in your Tauri application.
<Alert title="Note">
Tauri provides some functions to handle standard cases (like loading platform specific binaries), such as:
- `tauri::api::command::binary_command`, which will append the current environment triplet to the input (useful for cross-environments). If you're creating your own binary, you'll _have to_ provide a binary **for each platform you're targeting** by specifying the target triplets, e.g. "binaryname-x86_64-apple-darwin".
Target triplets can be found by executing the `rustup target list` command.
- `tauri::api::command::relative_command` that will relatively resolve the path to the binary.
</Alert>

151
docs/usage/guides/cli.md Normal file
View File

@ -0,0 +1,151 @@
---
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
},
{
"name": "destination",
"index": 2
}
]
}
```
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::cli::get_matches;
fn main() {
match get_matches() {
Some(matches) => {
// `matches` here is a Struct with { args, subcommand }
// where args is the HashMap mapping each arg's name to it's { value, occurrences }
// and subcommand is an Option of { name, matches }
}
}
}
```
### 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>.

218
docs/usage/guides/command.md Normal file
View File

@ -0,0 +1,218 @@
---
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 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");
}
```
## 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))
```

133
docs/usage/guides/events.md Normal file
View File

@ -0,0 +1,133 @@
---
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 { getCurrent, WebviewWindow } from '@tauri-apps/api/event'
// emit an event that are only visible to the current window
const current = getCurrent()
current.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");
}
```

335
docs/usage/guides/migration.md Normal file
View File

@ -0,0 +1,335 @@
---
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).

101
docs/usage/guides/plugin.md Normal file
View File

@ -0,0 +1,101 @@
---
title: Write Tauri Plugins
---
import Alert from '@theme/Alert'
<Alert title="Note" icon="info-alt">
Tauri will soon offer Plugin starter kits so the process of writing a Plugin crate will be simplified.
For now it's recommended to follow the [official Tauri plugins](#official-tauri-plugins).
</Alert>
The Tauri Plugin system was introduced in [tauri v0.8.0](https://docs.rs/tauri/0.8.0/tauri/).
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}, PageLoadPayload, Params, Window, InvokeMessage};
struct MyAwesomePlugin<M: Params> {
invoke_handler: Box<dyn Fn(InvokeMessage<M>) + 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 MyAwesomePlugin {
// 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<M: Params> Plugin<M> for MyAwesomePlugin<M> {
/// 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(&self, config: serde_json::Value) -> PluginResult<()> {
Ok(())
}
/// Callback invoked when the Window is created.
fn created(&self, window: Window<M>) {}
/// Callback invoked when the webview performs a navigation.
fn on_page_load(&self, window: Window<M>, payload: PageLoadPayload) {}
/// Extend the invoke handler.
fn extend_api(&mut self, message: InvokeMessage<M>) {
(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 (WIP)](https://github.com/tauri-apps/tauri-plugin-stronghold)
- [Authenticator (WIP)](https://github.com/tauri-apps/tauri-plugin-authenticator)
- [Logging (WIP)](https://github.com/tauri-apps/tauri-plugin-log)
- [SQL (WIP)](https://github.com/tauri-apps/tauri-plugin-sql)

308
docs/usage/guides/updater.md Normal file
View File

@ -0,0 +1,308 @@
---
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/app";
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 sign -g -w ~/.tauri/myapp.key
```
You have multiple options available
```bash
Tauri updates signer.
USAGE:
tauri 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)

5
docs/usage/guides/utils/multiwindow.md Normal file
View File

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

47
docs/usage/guides/visual/icons.md Normal file
View File

@ -0,0 +1,47 @@
---
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 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>

100
docs/usage/guides/visual/splashscreen.md Normal file
View File

@ -0,0 +1,100 @@
---
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
// Create the command:
#[tauri::command(with_window)]
fn close_splashscreen<M: Params>(window: tauri::Window<M>) {
// Close splashscreen
if let Ok(splashscreen) = window.get_webview("splashscreen") {
splashscreen.close().unwrap();
}
// Show main window
window.get_webview("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| {
// Run initialization code here
// ...
// After it's done, close the splashscreen and display the main window
if let Some(splashscreen) = app.get_window(&"splashscreen".into()) {
splashscreen.close().unwrap();
}
app.get_window(&"main".into()).unwrap().show().unwrap();
Ok(())
})
.run(tauri::generate_context!())
.expect("failed to run app");
}
```

92
docs/usage/guides/visual/window-customization.md Normal file
View File

@ -0,0 +1,92 @@
---
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:
TODO: LINKS
- [Through tauri.conf.json](https://tauri.studio/en/docs/api/config/#tauri.windows)
- [Through the JS API]
- [Through the Window in Rust]
## 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 class="drag-region 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:
TODO: TOGGLE MAXIMIZE
```js
import { appWindow } from '@tauri-apps/api/window'
document
.getElementById('titlebar-minimize')
.addEventListener('click', () => appWindow.minimize())
document
.getElementById('titlebar-maximize')
.addEventListener('click', () => appWindow.maximize())
document
.getElementById('titlebar-close')
.addEventListener('click', () => appWindow.close())
```

20
docs/usage/intro.md Normal file
View File

@ -0,0 +1,20 @@
---
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 add to your own project in order to fulfill your goals.
## A Step Further
- [Understanding Tauri Patterns](/docs/usage/patterns/about-patterns)
- [Add Tauri to my existing project](/docs/usage/development/integration)
- [Tauri Development Cycle](/docs/usage/development/development)
## Guides
- [How to embed custom binaries](/docs/usage/guides/bundler/sidecar)
- [How to customize app icons](/docs/usage/guides/visual/icons)

9
docs/usage/patterns/about-patterns.md Normal file
View File

@ -0,0 +1,9 @@
---
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 ["Getting started"](/docs/getting-started/intro) and become familiar with the basic architecture and terminology used in these patterns.

102
docs/usage/patterns/bridge.md Normal file
View File

@ -0,0 +1,102 @@
---
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/usage/patterns/cloudbridge.md Normal file
View File

@ -0,0 +1,102 @@
---
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/usage/patterns/cloudish.md Normal file
View File

@ -0,0 +1,89 @@
---
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/usage/patterns/glui.md Normal file
View File

@ -0,0 +1,91 @@
---
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/usage/patterns/hermit.md Normal file
View File

@ -0,0 +1,79 @@
---
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/usage/patterns/lockdown.md Normal file
View File

@ -0,0 +1,82 @@
---
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/usage/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/usage/patterns/multiwin.md Normal file
View File

@ -0,0 +1,92 @@
---
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"
}]
}
```