diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml index 81cdda1131..46c37fb410 100644 --- a/pnpm-lock.yaml +++ b/pnpm-lock.yaml @@ -15,16 +15,16 @@ importers: dependencies: '@astrojs/markdown-remark': specifier: ^4.2.1 - version: 4.3.1 + version: 4.3.0 '@astrojs/starlight': specifier: ^0.21.0 - version: 0.21.2(astro@4.5.8) + version: 0.21.2(astro@4.5.7) '@types/json-schema': specifier: ^7.0.15 version: 7.0.15 astro: specifier: ^4.4.4 - version: 4.5.8 + version: 4.5.7 astro-feelback: specifier: ^0.3.4 version: 0.3.4 @@ -48,10 +48,10 @@ importers: version: 1.2.0 starlight-blog: specifier: ^0.5.0 - version: 0.5.1(@astrojs/starlight@0.21.2)(astro@4.5.8) + version: 0.5.1(@astrojs/starlight@0.21.2)(astro@4.5.7) starlight-links-validator: specifier: ^0.6.0 - version: 0.6.0(@astrojs/starlight@0.21.2)(astro@4.5.8) + version: 0.6.0(@astrojs/starlight@0.21.2)(astro@4.5.7) packages/config-generator: dependencies: @@ -69,7 +69,7 @@ importers: version: 2.3.0 typescript: specifier: ^5.3.3 - version: 5.4.3 + version: 5.4.2 packages/i18n-tracker: devDependencies: @@ -111,7 +111,7 @@ importers: version: 2.3.0 typedoc: specifier: ^0.25.9 - version: 0.25.12(typescript@5.4.3) + version: 0.25.12(typescript@5.4.2) typedoc-plugin-markdown: specifier: 4.0.0-next.17 version: 4.0.0-next.17(patch_hash=kpxroq2vap5a4oc32rphk2cev4)(prettier@3.2.5)(typedoc@0.25.12) @@ -166,32 +166,7 @@ packages: - supports-color dev: false - /@astrojs/markdown-remark@4.3.1: - resolution: {integrity: sha512-eJFi600tkRjTFiwzY9oD8AgCgB7gFqyWCKWuZ33dATVBgLiROD+zlMZ8STZzU7+ZALvmiUAun/K7umTmP5YfVQ==} - dependencies: - '@astrojs/prism': 3.0.0 - github-slugger: 2.0.0 - hast-util-from-html: 2.0.1 - hast-util-to-text: 4.0.0 - import-meta-resolve: 4.0.0 - mdast-util-definitions: 6.0.0 - rehype-raw: 7.0.0 - rehype-stringify: 10.0.0 - remark-gfm: 4.0.0 - remark-parse: 11.0.0 - remark-rehype: 11.1.0 - remark-smartypants: 2.1.0 - shiki: 1.2.0 - unified: 11.0.4 - unist-util-remove-position: 5.0.0 - unist-util-visit: 5.0.0 - unist-util-visit-parents: 6.0.1 - vfile: 6.0.1 - transitivePeerDependencies: - - supports-color - dev: false - - /@astrojs/mdx@2.2.0(astro@4.5.8): + /@astrojs/mdx@2.2.0(astro@4.5.7): resolution: {integrity: sha512-EkcCniYdGwsh9k5LknqRrz/UyOnMNXdRk7fgDAw/zUDKnm7zgQAG8hIx0FxG1L2IINxLfu7IcjgZb3f5TFpxKw==} engines: {node: '>=18.14.1'} peerDependencies: @@ -200,7 +175,7 @@ packages: '@astrojs/markdown-remark': 4.3.0 '@mdx-js/mdx': 3.0.1 acorn: 8.11.3 - astro: 4.5.8 + astro: 4.5.7 es-module-lexer: 1.4.2 estree-util-visit: 2.0.0 github-slugger: 2.0.0 @@ -231,18 +206,18 @@ packages: zod: 3.22.4 dev: false - /@astrojs/starlight@0.21.2(astro@4.5.8): + /@astrojs/starlight@0.21.2(astro@4.5.7): resolution: {integrity: sha512-ziDfrbhBjw/+HwMITk6yz7SbkQKQJZY9GlaPHntSPq4kYs+b2ru3toIxj2l3T9LUFtUpNWHkj+C1wJTmfLZfaw==} peerDependencies: astro: ^4.2.7 dependencies: - '@astrojs/mdx': 2.2.0(astro@4.5.8) + '@astrojs/mdx': 2.2.0(astro@4.5.7) '@astrojs/sitemap': 3.1.1 '@pagefind/default-ui': 1.0.4 '@types/hast': 3.0.4 '@types/mdast': 4.0.3 - astro: 4.5.8 - astro-expressive-code: 0.33.5(astro@4.5.8) + astro: 4.5.7 + astro-expressive-code: 0.33.5(astro@4.5.7) bcp-47: 2.1.0 hast-util-from-html: 2.0.1 hast-util-select: 6.0.2 @@ -289,15 +264,15 @@ packages: engines: {node: '>=6.9.0'} dev: false - /@babel/core@7.24.3: - resolution: {integrity: sha512-5FcvN1JHw2sHJChotgx8Ek0lyuh4kCKelgMTTqhYJJtloNvUfpAFMeNQUtdlIaktwrSV9LtCdqwk48wL2wBacQ==} + /@babel/core@7.24.1: + resolution: {integrity: sha512-F82udohVyIgGAY2VVj/g34TpFUG606rumIHjTfVbssPg2zTR7PuuEpZcX8JA6sgBfIYmJrFtWgPvHQuJamVqZQ==} engines: {node: '>=6.9.0'} dependencies: '@ampproject/remapping': 2.3.0 '@babel/code-frame': 7.24.2 '@babel/generator': 7.24.1 '@babel/helper-compilation-targets': 7.23.6 - '@babel/helper-module-transforms': 7.23.3(@babel/core@7.24.3) + '@babel/helper-module-transforms': 7.23.3(@babel/core@7.24.1) '@babel/helpers': 7.24.1 '@babel/parser': 7.24.1 '@babel/template': 7.24.0 @@ -360,22 +335,22 @@ packages: '@babel/types': 7.24.0 dev: false - /@babel/helper-module-imports@7.24.3: - resolution: {integrity: sha512-viKb0F9f2s0BCS22QSF308z/+1YWKV/76mwt61NBzS5izMzDPwdq1pTrzf+Li3npBWX9KdQbkeCt1jSAM7lZqg==} + /@babel/helper-module-imports@7.24.1: + resolution: {integrity: sha512-HfEWzysMyOa7xI5uQHc/OcZf67/jc+xe/RZlznWQHhbb8Pg1SkRdbK4yEi61aY8wxQA7PkSfoojtLQP/Kpe3og==} engines: {node: '>=6.9.0'} dependencies: '@babel/types': 7.24.0 dev: false - /@babel/helper-module-transforms@7.23.3(@babel/core@7.24.3): + /@babel/helper-module-transforms@7.23.3(@babel/core@7.24.1): resolution: {integrity: sha512-7bBs4ED9OmswdfDzpz4MpWgSrV7FXlc3zIagvLFjS5H+Mk7Snr21vQ6QwrsoCGMfNC4e4LQPdoULEt4ykz0SRQ==} engines: {node: '>=6.9.0'} peerDependencies: '@babel/core': ^7.0.0 dependencies: - '@babel/core': 7.24.3 + '@babel/core': 7.24.1 '@babel/helper-environment-visitor': 7.22.20 - '@babel/helper-module-imports': 7.24.3 + '@babel/helper-module-imports': 7.24.1 '@babel/helper-simple-access': 7.22.5 '@babel/helper-split-export-declaration': 7.22.6 '@babel/helper-validator-identifier': 7.22.20 @@ -444,27 +419,27 @@ packages: '@babel/types': 7.24.0 dev: false - /@babel/plugin-syntax-jsx@7.24.1(@babel/core@7.24.3): + /@babel/plugin-syntax-jsx@7.24.1(@babel/core@7.24.1): resolution: {integrity: sha512-2eCtxZXf+kbkMIsXS4poTvT4Yu5rXiRa+9xGVT56raghjmBTKMpFNc9R4IDiB4emao9eO22Ox7CxuJG7BgExqA==} engines: {node: '>=6.9.0'} peerDependencies: '@babel/core': ^7.0.0-0 dependencies: - '@babel/core': 7.24.3 + '@babel/core': 7.24.1 '@babel/helper-plugin-utils': 7.24.0 dev: false - /@babel/plugin-transform-react-jsx@7.23.4(@babel/core@7.24.3): + /@babel/plugin-transform-react-jsx@7.23.4(@babel/core@7.24.1): resolution: {integrity: sha512-5xOpoPguCZCRbo/JeHlloSkTA8Bld1J/E1/kLfD1nsuiW1m8tduTA1ERCgIZokDflX/IBzKcqR3l7VlRgiIfHA==} engines: {node: '>=6.9.0'} peerDependencies: '@babel/core': ^7.0.0-0 dependencies: - '@babel/core': 7.24.3 + '@babel/core': 7.24.1 '@babel/helper-annotate-as-pure': 7.22.5 - '@babel/helper-module-imports': 7.24.3 + '@babel/helper-module-imports': 7.24.1 '@babel/helper-plugin-utils': 7.24.0 - '@babel/plugin-syntax-jsx': 7.24.1(@babel/core@7.24.3) + '@babel/plugin-syntax-jsx': 7.24.1(@babel/core@7.24.1) '@babel/types': 7.24.0 dev: false @@ -1632,12 +1607,12 @@ packages: hasBin: true dev: false - /astro-expressive-code@0.33.5(astro@4.5.8): + /astro-expressive-code@0.33.5(astro@4.5.7): resolution: {integrity: sha512-9JAyllueMUN8JTl/h/yTdbKinNmfalEWcV11s3lSf/UJQbAZfWJuy+IlGcArZDI/CmD21GXhFHLqYthpdY33ug==} peerDependencies: astro: ^4.0.0-beta || ^3.3.0 dependencies: - astro: 4.5.8 + astro: 4.5.7 hast-util-to-html: 8.0.4 remark-expressive-code: 0.33.5 dev: false @@ -1648,19 +1623,19 @@ packages: '@feelback/js': 0.3.4 dev: false - /astro@4.5.8: - resolution: {integrity: sha512-bhKsoZQWT6LW8aYMvTGglZTPa3rYRbcdc2buiJyFPCvSWOOyZmxqpp6vtQ+x6fXxD8P1NecM/c4g5GaPi+MokQ==} + /astro@4.5.7: + resolution: {integrity: sha512-Ioeg3TV42dOJvf6GlmykeR3EKZ8+JcnZyJ/X9qDPzVf2OREmtvW0182YCDXQBqwXFRHndZRcHLqinAWjzZYh/A==} engines: {node: '>=18.14.1', npm: '>=6.14.0'} hasBin: true dependencies: '@astrojs/compiler': 2.7.0 '@astrojs/internal-helpers': 0.3.0 - '@astrojs/markdown-remark': 4.3.1 + '@astrojs/markdown-remark': 4.3.0 '@astrojs/telemetry': 3.0.4 - '@babel/core': 7.24.3 + '@babel/core': 7.24.1 '@babel/generator': 7.24.1 '@babel/parser': 7.24.1 - '@babel/plugin-transform-react-jsx': 7.23.4(@babel/core@7.24.3) + '@babel/plugin-transform-react-jsx': 7.23.4(@babel/core@7.24.1) '@babel/traverse': 7.24.1 '@babel/types': 7.24.0 '@types/babel__core': 7.20.5 @@ -1709,8 +1684,8 @@ packages: tsconfck: 3.0.3 unist-util-visit: 5.0.0 vfile: 6.0.1 - vite: 5.2.2 - vitefu: 0.2.5(vite@5.2.2) + vite: 5.2.0 + vitefu: 0.2.5(vite@5.2.0) which-pm: 2.1.1 yargs-parser: 21.1.1 zod: 3.22.4 @@ -4845,27 +4820,27 @@ packages: resolution: {integrity: sha512-D9cPgkvLlV3t3IzL0D0YLvGA9Ahk4PcvVwUbN0dSGr1aP0Nrt4AEnTUbuGvquEC0mA64Gqt1fzirlRs5ibXx8g==} dev: false - /starlight-blog@0.5.1(@astrojs/starlight@0.21.2)(astro@4.5.8): + /starlight-blog@0.5.1(@astrojs/starlight@0.21.2)(astro@4.5.7): resolution: {integrity: sha512-3zJ7sJDe3rsE+9vJU/hDOKpKXEJwEMN0ha24DmKmKPKN5mtrN43p/ZJdrhRpb+PyJoJR4eNAtMLNgFyEu40cGA==} engines: {node: '>=18.14.1'} peerDependencies: '@astrojs/starlight': '>=0.19.0' astro: '>=4.2.7' dependencies: - '@astrojs/starlight': 0.21.2(astro@4.5.8) - astro: 4.5.8 + '@astrojs/starlight': 0.21.2(astro@4.5.7) + astro: 4.5.7 github-slugger: 2.0.0 dev: false - /starlight-links-validator@0.6.0(@astrojs/starlight@0.21.2)(astro@4.5.8): + /starlight-links-validator@0.6.0(@astrojs/starlight@0.21.2)(astro@4.5.7): resolution: {integrity: sha512-YXzKKZHM79ccBTO61l2WSmgdCG3406gldpVM6J2LhqZ5CeXsOgj6lho2xMLkc/p5nWcNSuYI2qNzsNUrLTmR5w==} engines: {node: '>=18.14.1'} peerDependencies: '@astrojs/starlight': '>=0.15.0' astro: '>=4.0.0' dependencies: - '@astrojs/starlight': 0.21.2(astro@4.5.8) - astro: 4.5.8 + '@astrojs/starlight': 0.21.2(astro@4.5.7) + astro: 4.5.7 github-slugger: 2.0.0 hast-util-from-html: 2.0.1 hast-util-has-property: 3.0.0 @@ -5139,7 +5114,7 @@ packages: typedoc: '>=0.24.0' dependencies: prettier: 3.2.5 - typedoc: 0.25.12(typescript@5.4.3) + typedoc: 0.25.12(typescript@5.4.2) dev: false patched: true @@ -5148,10 +5123,10 @@ packages: peerDependencies: typedoc: '>= 0.23.14 || 0.24.x || 0.25.x' dependencies: - typedoc: 0.25.12(typescript@5.4.3) + typedoc: 0.25.12(typescript@5.4.2) dev: false - /typedoc@0.25.12(typescript@5.4.3): + /typedoc@0.25.12(typescript@5.4.2): resolution: {integrity: sha512-F+qhkK2VoTweDXd1c42GS/By2DvI2uDF4/EpG424dTexSHdtCH52C6IcAvMA6jR3DzAWZjHpUOW+E02kyPNUNw==} engines: {node: '>= 16'} hasBin: true @@ -5162,11 +5137,11 @@ packages: marked: 4.3.0 minimatch: 9.0.3 shiki: 0.14.7 - typescript: 5.4.3 + typescript: 5.4.2 dev: false - /typescript@5.4.3: - resolution: {integrity: sha512-KrPd3PKaCLr78MalgiwJnA25Nm8HAmdwN3mYUYZgG/wizIo9EainNVQI9/yDavtVFRN2h3k8uf3GLHuhDMgEHg==} + /typescript@5.4.2: + resolution: {integrity: sha512-+2/g0Fds1ERlP6JsakQQDXjZdZMM+rqpamFZJEKh4kwTIn3iDkgKtby0CeNd5ATNZ4Ry1ax15TMx0W2V+miizQ==} engines: {node: '>=14.17'} hasBin: true dev: false @@ -5382,8 +5357,8 @@ packages: vfile-message: 4.0.2 dev: false - /vite@5.2.2: - resolution: {integrity: sha512-FWZbz0oSdLq5snUI0b6sULbz58iXFXdvkZfZWR/F0ZJuKTSPO7v72QPXt6KqYeMFb0yytNp6kZosxJ96Nr/wDQ==} + /vite@5.2.0: + resolution: {integrity: sha512-xMSLJNEjNk/3DJRgWlPADDwaU9AgYRodDH2t6oENhJnIlmU9Hx1Q6VpjyXua/JdMw1WJRbnAgHJ9xgET9gnIAg==} engines: {node: ^18.0.0 || >=20.0.0} hasBin: true peerDependencies: @@ -5417,7 +5392,7 @@ packages: fsevents: 2.3.3 dev: false - /vitefu@0.2.5(vite@5.2.2): + /vitefu@0.2.5(vite@5.2.0): resolution: {integrity: sha512-SgHtMLoqaeeGnd2evZ849ZbACbnwQCIwRH57t18FxcXoZop0uQu0uzlIhJBlF/eWVzuce0sHeqPcDo+evVcg8Q==} peerDependencies: vite: ^3.0.0 || ^4.0.0 || ^5.0.0 @@ -5425,7 +5400,7 @@ packages: vite: optional: true dependencies: - vite: 5.2.2 + vite: 5.2.0 dev: false /vscode-oniguruma@1.7.0: diff --git a/src/content/docs/features/positioner.mdx b/src/content/docs/features/positioner.mdx index 0a847b9306..cde8ad5f4d 100644 --- a/src/content/docs/features/positioner.mdx +++ b/src/content/docs/features/positioner.mdx @@ -3,12 +3,146 @@ title: Positioner description: Move windows to common locations. --- -import Stub from '@components/Stub.astro'; import PluginLinks from '@components/PluginLinks.astro'; +import { Steps, Tabs, TabItem } from '@astrojs/starlight/components'; +import CommandTabs from '@components/CommandTabs.astro'; - - Based on - https://github.com/tauri-apps/plugins-workspace/tree/v2/plugins/positioner - +Position your windows at well-known locations. + +This plugin is a port of [electron-positioner](https://github.com/jenslind/electron-positioner) for Tauri. + +## Supported Platforms + +- Windows +- Linux +- macOS + +## Setup + +_This plugin requires a Rust version of at least **1.75**_ + +Install the positioner plugin to get started. + +:::note +If you only intend on moving the window from Rust code, you only need the dependency in `src-tauri/Cargo.toml`, and can remove the plugin registration from `lib.rs` if you choose to setup automatically. +::: + + + + + Use your project's package manager to add the dependency: + + { ' ' } + + + + + + + 1. Install the positioner plugin by adding the following to your `Cargo.toml` file: + + ```toml title="src-tauri/Cargo.toml" + [dependencies] + tauri-plugin-positioner = "2.0.0-beta" + # alternatively with Git: + tauri-plugin-positioner = { git = "https://github.com/tauri-apps/plugins-workspace", branch = "v2" } + ``` + + 2. Modify `lib.rs` to initialize the plugin: + + ```rust title="src-tauri/src/lib.rs" ins={3} + fn run() { + tauri::Builder::default() + .plugin(tauri_plugin_positioner::init()) + .run(tauri::generate_context!()) + .expect("error while running tauri application"); + } + ``` + + 3. Install the JavaScript Guest bindings using your preferred JavaScript package manager: + + + + + + +Additional setup is required to get tray-relative positions to work. + + + 1. Add `tray-icon` feature to your `Cargo.toml` file: + ```toml title="src-tauri/Cargo.toml" ins={2} + [dependencies] + tauri-plugin-positioner = { version = "2.0.0-beta", features = ["tray-icon"] } + ``` + + 2. Setup `on_tray_event` for positioner plugin: + ```rust title="src-tauri/src/lib.rs" ins={4-12} + fn run() { + tauri::Builder::default() + .plugin(tauri_plugin_positioner::init()) + // This is required to get tray-relative positions to work + .setup(|app| { + TrayIconBuilder::new() + .on_tray_icon_event(|app, event| { + tauri_plugin_positioner::on_tray_event(app.app_handle(), &event); + }) + .build(app)?; + Ok(()) + }) + .run(tauri::generate_context!()) + .expect("error while running tauri application"); + } + ``` + + +## Usage + +The plugin's APIs are available through the JavaScript guest bindings: + +```javascript +import { moveWindow, Position } from "@tauri-apps/plugin-positioner"; + +moveWindow(Position.TopRight); +``` + +You can import and use the Window trait extension directly through Rust: + +```rust +use tauri_plugin_positioner::{WindowExt, Position}; + +let mut win = app.get_webview_window("main").unwrap(); +let _ = win.as_ref().window().move_window(Position::TopRight); +``` + +## Permissions + +By default all plugin commands are blocked and cannot be accessed. +You must define a list of permissions in your `capabilities` configuration. + +See [Access Control List](/references/v2/acl) for more information. + +```json title="src-tauri/capabilities/main.json" ins={4} +{ + "permissions": [ + ..., + "positioner:default", + ] +} +``` + +| Permission | Description | +| ----------------------------------------- | -------------------------------------------------------------------------- | +| `positioner:allow-move-window` | Enables the move_window command without any pre-configured scope. | +| `positioner:deny-move-window` | Denies the move_window command without any pre-configured scope. | +| `positioner:default` | Allows the move_window command. | diff --git a/src/content/docs/features/updater.mdx b/src/content/docs/features/updater.mdx index 7b0af71567..0c694d4b0e 100644 --- a/src/content/docs/features/updater.mdx +++ b/src/content/docs/features/updater.mdx @@ -3,367 +3,12 @@ title: Updater description: In-app updates for Tauri applications. --- +import Stub from '@components/Stub.astro'; import PluginLinks from '@components/PluginLinks.astro'; -import { Aside, Steps, Tabs, TabItem } from '@astrojs/starlight/components'; -import CommandTabs from '@components/CommandTabs.astro'; -The Updater plugin offers an update mechanism for Tauri applications distributed via: - -- NSIS (Windows) -- MSI (Windows) -- AppImage (Linux) -- App bundle (macOS) - -Once your Tauri project is ready, you can configure Tauri's updater to enable auto updating for your users. - - - -## Supported Platforms - -- Windows -- Linux -- macOS - -## Setup - -_This plugin requires a Rust version of at least **1.75**_ - -Install the updater plugin to get started. - - - - Use your project's package manager to add the dependency: - - { ' ' } - - - - - - 1. Install the updater plugin by adding the following to your `Cargo.toml` file: - - ```toml title="src-tauri/Cargo.toml" - # you can add the dependencies on the `[dependencies]` section if you do not target mobile - [target."cfg(not(any(target_os = \"android\", target_os = \"ios\")))".dependencies] - tauri-plugin-updater = "2.0.0-beta" - # alternatively with Git: - tauri-plugin-updater = { git = "https://github.com/tauri-apps/plugins-workspace", branch = "v2" } - ``` - - 2. Modify `lib.rs` to initialize the plugin: - - ```rust title="src-tauri/src/lib.rs" ins={3-7} - fn run() { - tauri::Builder::default() - .setup(|app| { - #[cfg(desktop)] - app.handle().plugin(tauri_plugin_updater::Builder::new().build())?; - Ok(()) - }) - .run(tauri::generate_context!()) - .expect("error while running tauri application"); - } - ``` - - 3. Install the JavaScript Guest bindings using your preferred JavaScript package manager: - - - - - - - -## Signing Updates - -Tauri's cli has a built-in signature mechanism to ensure that updates are safe to be installed. - -To sign your updates you need two things: - -1. The _public key_, which will be added to your `tauri.conf.json` file later, to validate update artifacts before the installation. -2. The _private key_, which is used to sign your update artifacts and should NEVER be shared with anyone. Also, if you lose this key, you will NOT be able to publish new updates to your current user base. It is crucial to store it in a safe place where you can always access it. - -To generate the keys on Linux and macOS you can use the Tauri CLI: - - - -If you are on Windows, you should use `$HOME/.tauri/myapp.key` or a different path of your choice instead: - - - -## Tauri Configuration - -Now you need to configure Tauri's updater. To do this, add this to your Tauri config: - -```json title="tauri.conf.json" -{ - "plugins": { - "updater": { - "endpoints": [ - "https://releases.myapp.com/{{target}}/{{arch}}/{{current_version}}" - ], - "pubkey": "YOUR_UPDATER_SIGNATURE_PUBKEY_HERE", - "windows": { - "installMode": "passive", - "installerArgs": [] - } - } - } -} -``` - -The required keys are `"endpoints"` and `"pubkey"` to enable the updater. The `"endpoints"` field can also be set later in Rust. - -`"endpoints"`: must be an array of updater endpoint URLs as strings. TLS is enforced in production mode.
-All endpoints should generally return the same content, Tauri will fall back to the next endpoint URL if it couldn't connect to the first one or if it returned a non-2XX status code.
-Each updater URL can contain the following variables allowing you to determine [server-side](#static-json-file) if an update is available: - -- `{{current_version}}`: The version of the app that is requesting the update. -- `{{target}}`: The operating system name (one of `linux`, `windows` or `darwin`). -- `{{arch}}`: The architecture of the machine (one of `x86_64`, `i686`, `aarch64` or `armv7`). - -`"pubkey"`: must be a valid public key generated with Tauri's CLI [above](#signing-updates). - -`"windows"`: (optional) The [Windows configuration](#windows-configuration) for the updater. - -### Windows Configuration - -`"installMode"`: The installation mode for the update on Windows. Defaults to `passive`. Can be any **ONE** of the following types: - -- `"passive"`: There will be a small window with a progress bar. The update will be installed without requiring any user interaction. Generally recommended and the default mode. -- `"basicUi"`: There will be a basic user interface shown which requires user interaction to finish the installation. -- `"quiet"`: There will be no progress feedback to the user. With this mode the installer cannot request admin privileges by itself so it only works in user-wide installations or when your app itself already runs with admin privileges. Generally not recommended. - -`"installerArgs"`: Array of command string. Additional arguments given to the NSIS or WiX installer. - -## Update Artifacts - -Tauri's bundler will automatically generate and sign update artifacts once the updater is correctly configured and enabled. - -Before building your app, you need to set environment variables for the private key and password: - -- `TAURI_SIGNING_PRIVATE_KEY`: Path or content of your private key -- `TAURI_SIGNING_PRIVATE_KEY_PASSWORD`: Your private key password (optional) - -If you want to set these variables for the current console session you could execute these commands in the console which you will use to build the app later: - - - - ```shell export TAURI_SIGNING_PRIVATE_KEY="content of the generated key" - export TAURI_SIGNING_PRIVATE_KEY_PASSWORD="password" ``` - - - ```powershell $env:TAURI_SIGNING_PRIVATE_KEY="content of the generated key" - $env:TAURI_SIGNING_PRIVATE_KEY_PASSWORD="password" ``` - - - -After that, you can run `tauri build` as usual and Tauri will generate the update bundle and its signature. - -- **Linux**: On Linux, Tauri will create a `.tar.gz` archive from the AppImage inside the `target/release/bundle/appimage/` folder: - - - `myapp.AppImage` - the standard app bundle. - - `myapp.AppImage.tar.gz` - the updater bundle. - - `myapp.AppImage.tar.gz.sig` - the signature of the update bundle. - -- **macOS**: On macOS, Tauri will create a `.tar.gz` archive from the application bundle inside the `target/release/bundle/macos/` folder: - - - `myapp.app` - the standard app bundle. - - `myapp.app.tar.gz` - the updater bundle. - - `myapp.app.tar.gz.sig` - the signature of the update bundle. - -- **Windows**: On Windows, Tauri will create `.zip` archives from the MSI and NSIS installers inside the `target/release/bundle/msi/` and `target/release/bundle/nsis` folders: - - `myapp-setup.exe` - the standard app bundle. - - `myapp-setup.nsis.zip` - the updater bundle. - - `myapp-setup.nsis.zip.sig` - the signature of the update bundle. - - `myapp.msi` - the standard app bundle. - - `myapp.msi.zip` - the updater bundle. - - `myapp.msi.zip.sig` - the signature of the update bundle. - -The signature can be uploaded and shared safely as long as your private key is secure. - -## Server Support - -Tauri's updater supports two ways of announcing update data: - -- A static JSON file (to use on services like S3 or GitHub gists) -- A dynamic update server - -The static JSON file is easier to use while a dynamic update server will give you finer control over the update mechanism. - -### Static JSON File - -With this approach, Tauri will always request the same JSON file and determine if the app needs to be updated by comparing the version field of the response with the requesting app's current version. Tauri will expect a response in this format: - -```json -{ - "version": "v1.0.0", - "notes": "Test version", - "pub_date": "2020-06-22T19:25:57Z", - "platforms": { - "darwin-x86_64": { - "signature": "Content of app.tar.gz.sig", - "url": "https://github.com/username/reponame/releases/download/v1.0.0/app-x86_64.app.tar.gz" - }, - "darwin-aarch64": { - "signature": "Content of app.tar.gz.sig", - "url": "https://github.com/username/reponame/releases/download/v1.0.0/app-aarch64.app.tar.gz" - }, - "linux-x86_64": { - "signature": "Content of app.AppImage.tar.gz.sig", - "url": "https://github.com/username/reponame/releases/download/v1.0.0/app-amd64.AppImage.tar.gz" - }, - "windows-x86_64": { - "signature": "Content of app-setup.nsis.sig or app.msi.sig, depending on the chosen format", - "url": "https://github.com/username/reponame/releases/download/v1.0.0/app-x64-setup.nsis.zip" - } - } -} -``` - -The required keys are `"version"`, `"platforms.[target].url"` and `"platforms.[target].signature"`; the others are optional. - -- `"version"` must be a valid semver, with or without a leading `v`, meaning that both `1.0.0` and `v1.0.0` are valid. -- `"platforms"`: Each platform key is in the `OS-ARCH` format, where `OS` is one of `linux`, `darwin` or `windows`, and `ARCH` is one of `x86_64`, `aarch64`, `i686` or `armv7`. -- `"url"` must be a valid url to the update bundle. -- `"signature"` must be the **content** of the generated `.sig` file. The signature may change each time you run `tauri build` so make sure to always update it. -- `"notes"`: Here you can add notes about the update, like release notes. -- `"pub_date"` must be formatted according to [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.8) if present. - -Note that Tauri will validate the _whole_ file before checking the version field, so make sure all existing platform configurations are valid and complete. - -### Dynamic Update Server - -With this approach, Tauri will follow the update server's instructions. To disable the internal version check you can [overwrite Tauri's version comparison](https://docs.rs/tauri-plugin-updater/latest/tauri_plugin_updater/struct.UpdaterBuilder.html#method.version_comparator) to always install the version sent by the server. This could be useful if you need to roll back your app version quickly. - -Your server can use variables defined in the [`endpoint`](#config-enpoints) url above to determine if an update is required. If you need more data, you can include additional [request headers in Rust](https://docs.rs/tauri-plugin-updater/latest/tauri_plugin_updater/struct.UpdaterBuilder.html#method.header) to your liking. - -Your server should respond with a status code of [`204 No Content`](http://tools.ietf.org/html/rfc2616#section-10.2.5) if there is no update available. - -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 a JSON response in this format: - -```json -{ - "version": "0.2.0", - "pub_date": "2020-09-18T12:29:53+01:00", - "url": "https://mycompany.example.com/myapp/releases/myrelease.tar.gz", - "signature": "Content of the relevant .sig file", - "notes": "These are some release notes" -} -``` - -The required keys are "url", "version" and "signature"; the others are optional. - -- `"version"` must be a valid semver, with or without a leading `v`, meaning that both `1.0.0` and `v1.0.0` are valid. -- `"url"` must be a valid url to the update bundle. -- `"signature"` must be the **content** of the generated `.sig` file. The signature may change each time you run `tauri build` so make sure to always update it. -- `"notes"`: Here you can add notes about the update, like release notes. -- `"pub_date"` must be formatted according to [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.8) if present. - -## Usage - - - - ```js - import { check } from "@tauri-apps/plugin-updater"; - - const update = await check(); - if (update?.available) { - await update.downloadAndInstall(); - } - ``` - - - ```rust title="src-tauri/src/lib.rs" - use tauri_plugin_updater::UpdaterExt; - - fn run() { - tauri::Builder::default() - .plugin(tauri_plugin_updater::Builder::new().build()) - .setup(|app| { - let app_handle = app.handle().clone(); - tauri::async_runtime::spawn(async move { - let builder = app_handle.updater_builder(); - let updater = builder.build().unwrap(); - - match updater.check().await { - Ok(Some(update)) => { - if let Err(e) = update - .download_and_install( - || {}, - || { - println!("Download complete."); - }, - ) - .await - { - println!("Failed to download and install the update: {e}"); - } else { - println!("Update complete."); - } - } - Ok(None) => { - println!("No updates available."); - } - Err(e) => { - println!("Failed to check for updates: {e}"); - } - } - }); - Ok(()) - }) - .run(tauri::generate_context!()) - .expect("error while running tauri application"); - } - ``` - - - - -## Permissions - -By default, all plugin commands are blocked and cannot be accessed. You must define a list of permissions in your `capabilities` configuration. - -See [Access Control List](/references/v2/acl) for more information. - -```json title="src-tauri/capabilities/main.json" ins={6} -{ - "$schema": "../gen/schemas/desktop-schema.json", - "identifier": "main-capability", - "description": "Capability for the main window", - "windows": ["main"], - "permissions": ["updater:default"] -} -``` - -| Permission | Description | -| ------------------------------------ | -------------------------------------------------------------------------- | -| `updater:default` | Allows checking for new updates and installing them | -| `updater:allow-check` | Enables the check command without any pre-configured scope. | -| `updater:deny-check` | Denies the check command without any pre-configured scope. | -| `updater:allow-download-and-install` | Enables the download_and_install command without any pre-configured scope. | -| `updater:deny-download-and-install` | Denies the download_and_install command without any pre-configured scope. | + + Based on + https://github.com/tauri-apps/plugins-workspace/tree/v2/plugins/updater + diff --git a/src/content/docs/guides/upgrade-migrate/from-tauri-1.mdx b/src/content/docs/guides/upgrade-migrate/from-tauri-1.mdx index d42bc1e5bc..fa79fbac9a 100644 --- a/src/content/docs/guides/upgrade-migrate/from-tauri-1.mdx +++ b/src/content/docs/guides/upgrade-migrate/from-tauri-1.mdx @@ -53,7 +53,7 @@ The Tauri v2 CLI includes a `migrate` command that automates most of the process