From 08f90f0fb4a307488a1c1dbd2526ade239aac6ec Mon Sep 17 00:00:00 2001 From: Jonas Kruckenberg Date: Fri, 6 Jan 2023 14:21:57 +0100 Subject: [PATCH] update readmes --- plugins/authenticator/README.md | 71 ++++++++++++++++++++++++++++++- plugins/autostart/README.md | 46 +++++++++++++++++++- plugins/fs-extra/README.md | 44 +++++++++++++++++-- plugins/fs-watch/README.md | 49 ++++++++++++++++++++- plugins/localhost/README.md | 48 ++++++++++++++++++--- plugins/log/README.md | 65 +++++++++++++++++++++++++++- plugins/persisted-scope/README.md | 28 ++++++++++-- plugins/positioner/README.md | 70 +++++++++++++++++++++++++++++- plugins/sql/README.md | 51 +++++++++++++++++++++- plugins/store/README.md | 47 +++++++++++++++++++- plugins/stronghold/README.md | 47 +++++++++++++++++++- plugins/upload/README.md | 47 +++++++++++++++++++- plugins/websocket/README.md | 44 ++++++++++++++++++- plugins/window-state/README.md | 42 +++++++++++++++++- shared/template/README.md | 40 ++++++++++++++++- 15 files changed, 703 insertions(+), 36 deletions(-) diff --git a/plugins/authenticator/README.md b/plugins/authenticator/README.md index 9b0fdcbe..fe455bb6 100644 --- a/plugins/authenticator/README.md +++ b/plugins/authenticator/README.md @@ -1,17 +1,84 @@ ![plugin-authenticator](banner.png) - +Use Hardware Security-keys in your Tauri App. ## Install +There are three general methods of installation that we can recommend. + +1. Use crates.io and npm (easiest, and requires you to trust that our publishing pipeline worked) +2. Pull sources directly from Github using git tags / revision hashes (most secure) +3. Git submodule install this repo in your tauri project and then use file protocol to ingest the source (most secure, but inconvenient to use) + +Install the Core plugin by adding the following to your `Cargo.toml` file: + +`src-tauri/Cargo.toml` +```toml +[dependencies] +tauri-plugin-authenticator = { git = "https://github.com/tauri-apps/plugins-workspace", branch = "dev" } ``` +You can install the JavaScript Guest bindings using your preferred JavaScript package manager: + +> Note: Since most JavaScript package managers are unable to install packages from git monorepos we provide read-only mirrors of each plugin. This makes installation option 2 more ergonomic to use. + +```sh +pnpm add https://github.com/tauri-apps/tauri-plugin-authenticator +# or +npm add https://github.com/tauri-apps/tauri-plugin-authenticator +# or +yarn add https://github.com/tauri-apps/tauri-plugin-authenticator ``` ## Usage +First you need to register the core plugin with Tauri: + +`src-tauri/src/main.rs` +```rust +fn main() { + tauri::Builder::default() + .plugin(tauri_plugin_authenticator::init()) + .run(tauri::generate_context!()) + .expect("error while running tauri application"); +} ``` +Afterwards all the plugin's APIs are available through the JavaScript guest bindings: + +```javascript +import { Authenticator } from 'tauri-plugin-authenticator-api' + +const auth = new Authenticator() +auth.init() // initialize transports + +// generate a 32-bytes long random challenge +const arr = new Uint32Array(32) +window.crypto.getRandomValues(arr) +const b64 = btoa(String.fromCharCode.apply(null, arr)) +// web-safe base64 +const challenge = b64.replace(/\+/g, '-').replace(/\//g, '_') + +const domain = 'https://tauri.app' + +// attempt to register with the security key +const json = await auth.register(challenge, domain) +const registerResult = JSON.parse(json) + +// verify te registration was successfull +const r2 = await auth.verifyRegistration(challenge, app, registerResult.registerData, registerResult.clientData) +const j2 = JSON.parse(r2) + +// sign some data +const json = await auth.sign(challenge, app, keyHandle) +const signData = JSON.parse(json) + +// verify the signature again +const counter = await auth.verifySignature(challenge, app, signData.signData, clientData, keyHandle, pubkey) + +if(counter && counter>0) { + console.log('SUCCESS!') +} ``` ## Contributing @@ -20,6 +87,6 @@ PRs accepted. Please make sure to read the Contributing Guide before making a pu ## License -Code: (c) 2015 - 2021 - The Tauri Programme within The Commons Conservancy. +Code: (c) 2015 - Present - The Tauri Programme within The Commons Conservancy. MIT or MIT/Apache 2.0 where applicable. diff --git a/plugins/autostart/README.md b/plugins/autostart/README.md index 6fb45653..f048cd13 100644 --- a/plugins/autostart/README.md +++ b/plugins/autostart/README.md @@ -1,17 +1,59 @@ ![plugin-autostart](banner.png) - +Automatically launch your application at startup. Supports Windows, Mac (via AppleScript or Launch Agent), and Linux. ## Install +There are three general methods of installation that we can recommend. + +1. Use crates.io and npm (easiest, and requires you to trust that our publishing pipeline worked) +2. Pull sources directly from Github using git tags / revision hashes (most secure) +3. Git submodule install this repo in your tauri project and then use file protocol to ingest the source (most secure, but inconvenient to use) + +Install the Core plugin by adding the following to your `Cargo.toml` file: + +`src-tauri/Cargo.toml` +```toml +[dependencies] +tauri-plugin-autostart = { git = "https://github.com/tauri-apps/plugins-workspace", branch = "dev" } ``` +You can install the JavaScript Guest bindings using your preferred JavaScript package manager: + +> Note: Since most JavaScript package managers are unable to install packages from git monorepos we provide read-only mirrors of each plugin. This makes installation option 2 more ergonomic to use. + +```sh +pnpm add https://github.com/tauri-apps/tauri-plugin-autostart +# or +npm add https://github.com/tauri-apps/tauri-plugin-autostart +# or +yarn add https://github.com/tauri-apps/tauri-plugin-autostart ``` ## Usage +First you need to register the core plugin with Tauri: + +`src-tauri/src/main.rs` +```rust +fn main() { + tauri::Builder::default() + .plugin(tauri_plugin_autostart::init(MacosLauncher::LaunchAgent, Some(vec!["--flag1", "--flag2"]) /* arbitrary number of args to pass to your app */)) + .run(tauri::generate_context!()) + .expect("error while running tauri application"); +} ``` +Afterwards all the plugin's APIs are available through the JavaScript guest bindings: + +```javascript +import { enable, isEnabled, disable } from 'tauri-plugin-autostart-api' + +await enable() + +console.log(`registered for autostart? ${await isEnabled()}`) + +disable() ``` ## Contributing @@ -20,6 +62,6 @@ PRs accepted. Please make sure to read the Contributing Guide before making a pu ## License -Code: (c) 2015 - 2021 - The Tauri Programme within The Commons Conservancy. +Code: (c) 2015 - Present - The Tauri Programme within The Commons Conservancy. MIT or MIT/Apache 2.0 where applicable. diff --git a/plugins/fs-extra/README.md b/plugins/fs-extra/README.md index 6047161d..f2b74924 100644 --- a/plugins/fs-extra/README.md +++ b/plugins/fs-extra/README.md @@ -1,17 +1,53 @@ -![plugin-fs-extra](banner.png) - ## Install +There are three general methods of installation that we can recommend. + +1. Use crates.io and npm (easiest, and requires you to trust that our publishing pipeline worked) +2. Pull sources directly from Github using git tags / revision hashes (most secure) +3. Git submodule install this repo in your tauri project and then use file protocol to ingest the source (most secure, but inconvenient to use) + +Install the Core plugin by adding the following to your `Cargo.toml` file: + +`src-tauri/Cargo.toml` +```toml +[dependencies] +tauri-plugin-fs-extra = { git = "https://github.com/tauri-apps/plugins-workspace", branch = "dev" } ``` +You can install the JavaScript Guest bindings using your preferred JavaScript package manager: + +> Note: Since most JavaScript package managers are unable to install packages from git monorepos we provide read-only mirrors of each plugin. This makes installation option 2 more ergonomic to use. + +```sh +pnpm add https://github.com/tauri-apps/tauri-plugin-fs-extra +# or +npm add https://github.com/tauri-apps/tauri-plugin-fs-extra +# or +yarn add https://github.com/tauri-apps/tauri-plugin-fs-extra ``` ## Usage +First you need to register the core plugin with Tauri: + +`src-tauri/src/main.rs` +```rust +fn main() { + tauri::Builder::default() + .plugin(tauri_plugin_fs_extra::init()) + .run(tauri::generate_context!()) + .expect("error while running tauri application"); +} ``` +Afterwards all the plugin's APIs are available through the JavaScript guest bindings: + +```javascript +import { metadata } from 'tauri-plugin-fs-extra-api' + +await metadata('/path/to/file') ``` ## Contributing @@ -20,6 +56,6 @@ PRs accepted. Please make sure to read the Contributing Guide before making a pu ## License -Code: (c) 2015 - 2021 - The Tauri Programme within The Commons Conservancy. +Code: (c) 2015 - Present - The Tauri Programme within The Commons Conservancy. -MIT or MIT/Apache 2.0 where applicable. +MIT or MIT/Apache 2.0 where applicable. \ No newline at end of file diff --git a/plugins/fs-watch/README.md b/plugins/fs-watch/README.md index 1c11acf0..4a0d65c0 100644 --- a/plugins/fs-watch/README.md +++ b/plugins/fs-watch/README.md @@ -1,17 +1,62 @@ ![plugin-fs-watch](banner.png) - +Watch changes on files and directories through [notify](https://github.com/notify-rs/notify). ## Install +There are three general methods of installation that we can recommend. + +1. Use crates.io and npm (easiest, and requires you to trust that our publishing pipeline worked) +2. Pull sources directly from Github using git tags / revision hashes (most secure) +3. Git submodule install this repo in your tauri project and then use file protocol to ingest the source (most secure, but inconvenient to use) + +Install the Core plugin by adding the following to your `Cargo.toml` file: + +`src-tauri/Cargo.toml` +```toml +[dependencies] +tauri-plugin-fs-watch = { git = "https://github.com/tauri-apps/plugins-workspace", branch = "dev" } ``` +You can install the JavaScript Guest bindings using your preferred JavaScript package manager: + +> Note: Since most JavaScript package managers are unable to install packages from git monorepos we provide read-only mirrors of each plugin. This makes installation option 2 more ergonomic to use. + +```sh +pnpm add https://github.com/tauri-apps/tauri-plugin-fs-watch +# or +npm add https://github.com/tauri-apps/tauri-plugin-fs-watch +# or +yarn add https://github.com/tauri-apps/tauri-plugin-fs-watch ``` ## Usage +First you need to register the core plugin with Tauri: + +`src-tauri/src/main.rs` +```rust +fn main() { + tauri::Builder::default() + .plugin(tauri_plugin_fs_watch::init()) + .run(tauri::generate_context!()) + .expect("error while running tauri application"); +} ``` +Afterwards all the plugin's APIs are available through the JavaScript guest bindings: + +```javascript +import { watch, watchImmediate } from 'tauri-plugin-fs-watch-api' + +// can also watch an array of paths +const stopWatching = await watch('/path/to/something', { recursive: true }, event => { + const { type, payload } = event +}) + +const stopRawWatcher = await watchImmediate(['/path/a', '/path/b'], {}, event => { + const { path, operation, cookie } = event +}) ``` ## Contributing @@ -20,6 +65,6 @@ PRs accepted. Please make sure to read the Contributing Guide before making a pu ## License -Code: (c) 2015 - 2021 - The Tauri Programme within The Commons Conservancy. +Code: (c) 2015 - Present - The Tauri Programme within The Commons Conservancy. MIT or MIT/Apache 2.0 where applicable. diff --git a/plugins/localhost/README.md b/plugins/localhost/README.md index 66c0c587..e5c495f1 100644 --- a/plugins/localhost/README.md +++ b/plugins/localhost/README.md @@ -1,17 +1,55 @@ ![plugin-localhost](banner.png) - +Expose your apps assets through a localhost server instead of the default custom protocol. + +> Note: This plugins brings considerable security risks and you should only use it if you know what your are doing. If in doubt, use the default custom protocol implementation. ## Install -``` +There are three general methods of installation that we can recommend. -``` +1. Use crates.io and npm (easiest, and requires you to trust that our publishing pipeline worked) +2. Pull sources directly from Github using git tags / revision hashes (most secure) +3. Git submodule install this repo in your tauri project and then use file protocol to ingest the source (most secure, but inconvenient to use) -## Usage +Install the Core plugin by adding the following to your `Cargo.toml` file: +`src-tauri/Cargo.toml` +```toml +[dependencies] +tauri-plugin-localhost = { git = "https://github.com/tauri-apps/plugins-workspace", branch = "dev" } +portpicker = "0.1" # used in the example to pick a random free port ``` +## Usage + +First you need to register the core plugin with Tauri: + +`src-tauri/src/main.rs` +```rust +use tauri::{utils::config::AppUrl, window::WindowBuilder, WindowUrl}; + +fn main() { + let port = portpicker::pick_unused_port().expect("failed to find unused port"); + + let mut context = tauri::generate_context!(); + let url = format!("http://localhost:{}", port).parse().unwrap(); + let window_url = WindowUrl::External(url); + // rewrite the config so the IPC is enabled on this URL + context.config_mut().build.dist_dir = AppUrl::Url(window_url.clone()); + context.config_mut().build.dev_path = AppUrl::Url(window_url.clone()); + + tauri::Builder::default() + .plugin(tauri_plugin_localhost::Builder::new(port).build()) + .setup(move |app| { + WindowBuilder::new(app, "main".to_string(), window_url) + .title("Localhost Example") + .build()?; + Ok(()) + }) + .run(context) + .expect("error while running tauri application"); +} ``` ## Contributing @@ -20,6 +58,6 @@ PRs accepted. Please make sure to read the Contributing Guide before making a pu ## License -Code: (c) 2015 - 2021 - The Tauri Programme within The Commons Conservancy. +Code: (c) 2015 - Present - The Tauri Programme within The Commons Conservancy. MIT or MIT/Apache 2.0 where applicable. diff --git a/plugins/log/README.md b/plugins/log/README.md index 79504c98..2d691449 100644 --- a/plugins/log/README.md +++ b/plugins/log/README.md @@ -1,25 +1,86 @@ ![plugin-log](banner.png) - +Configurable logging for your Tauri app. ## Install +There are three general methods of installation that we can recommend. + +1. Use crates.io and npm (easiest, and requires you to trust that our publishing pipeline worked) +2. Pull sources directly from Github using git tags / revision hashes (most secure) +3. Git submodule install this repo in your tauri project and then use file protocol to ingest the source (most secure, but inconvenient to use) + +Install the Core plugin by adding the following to your `Cargo.toml` file: + +`src-tauri/Cargo.toml` +```toml +[dependencies] +tauri-plugin-log = { git = "https://github.com/tauri-apps/plugins-workspace", branch = "dev" } ``` +You can install the JavaScript Guest bindings using your preferred JavaScript package manager: + +> Note: Since most JavaScript package managers are unable to install packages from git monorepos we provide read-only mirrors of each plugin. This makes installation option 2 more ergonomic to use. + +```sh +pnpm add https://github.com/tauri-apps/tauri-plugin-log +# or +npm add https://github.com/tauri-apps/tauri-plugin-log +# or +yarn add https://github.com/tauri-apps/tauri-plugin-log ``` ## Usage +First you need to register the core plugin with Tauri: + +`src-tauri/src/main.rs` +```rust +use tauri_plugin_log::{LogTarget}; + +fn main() { + tauri::Builder::default() + .plugin(tauri_plugin_log::Builder::default().targets([ + LogTarget::LogDir, + LogTarget::Stdout, + LogTarget::Webview, + ]).build()) + .run(tauri::generate_context!()) + .expect("error while running tauri application"); +} ``` +Afterwards all the plugin's APIs are available through the JavaScript guest bindings: + +```javascript +import { trace, info, error, attachConsole } from 'tauri-plugin-log-api' + +// with LogTarget::Webview enabled this function will print logs to the browser console +const detach = await attachConsole() + +trace("Trace") +info("Info") +error("Error") + +// detach the browser console from the log stream +detach() ``` +To log from rust code, add the log crate to your `Cargo.toml`: + +```toml +[dependencies] +log = "^0.4" +``` + +Now, you can use the macros provided by the log crate to log messages from your backend. See the [docs](https://docs.rs/log/latest) for more details. + ## Contributing PRs accepted. Please make sure to read the Contributing Guide before making a pull request. ## License -Code: (c) 2015 - 2021 - The Tauri Programme within The Commons Conservancy. +Code: (c) 2015 - Present - The Tauri Programme within The Commons Conservancy. MIT or MIT/Apache 2.0 where applicable. diff --git a/plugins/persisted-scope/README.md b/plugins/persisted-scope/README.md index 3891b209..a856a777 100644 --- a/plugins/persisted-scope/README.md +++ b/plugins/persisted-scope/README.md @@ -1,25 +1,45 @@ ![plugin-persisted-scope](banner.png) - +Save filesystem and asset scopes and restore them when the app is reopened. ## Install -``` +There are three general methods of installation that we can recommend. + +1. Use crates.io and npm (easiest, and requires you to trust that our publishing pipeline worked) +2. Pull sources directly from Github using git tags / revision hashes (most secure) +3. Git submodule install this repo in your tauri project and then use file protocol to ingest the source (most secure, but inconvenient to use) + +Install the Core plugin by adding the following to your `Cargo.toml` file: +`src-tauri/Cargo.toml` +```toml +[dependencies] +tauri-plugin-persisted-scope = { git = "https://github.com/tauri-apps/plugins-workspace", branch = "dev" } ``` ## Usage -``` +First you need to register the core plugin with Tauri: +`src-tauri/src/main.rs` +```rust +fn main() { + tauri::Builder::default() + .plugin(tauri_plugin_persisted_scope::init()) + .run(tauri::generate_context!()) + .expect("error while running tauri application"); +} ``` +Afterwards the plugin will automatically save and restore filesystem and asset scopes. + ## Contributing PRs accepted. Please make sure to read the Contributing Guide before making a pull request. ## License -Code: (c) 2015 - 2021 - The Tauri Programme within The Commons Conservancy. +Code: (c) 2015 - Present - The Tauri Programme within The Commons Conservancy. MIT or MIT/Apache 2.0 where applicable. diff --git a/plugins/positioner/README.md b/plugins/positioner/README.md index 5eb5195e..8625f15f 100644 --- a/plugins/positioner/README.md +++ b/plugins/positioner/README.md @@ -1,17 +1,82 @@ ![plugin-positioner](banner.png) - +Position your windows at well-known locations. + +This plugin is a port of [electron-positioner](https://github.com/jenslind/electron-positioner) for Tauri. ## Install +There are three general methods of installation that we can recommend. + +1. Use crates.io and npm (easiest, and requires you to trust that our publishing pipeline worked) +2. Pull sources directly from Github using git tags / revision hashes (most secure) +3. Git submodule install this repo in your tauri project and then use file protocol to ingest the source (most secure, but inconvenient to use) + +Install the Core plugin by adding the following to your `Cargo.toml` file: + +`src-tauri/Cargo.toml` +```toml +[dependencies] +tauri-plugin-positioner = "1.0" +# or through git +tauri-plugin-positioner = { git = "https://github.com/tauri-apps/plugins-workspace", branch = "dev" } ``` +You can install the JavaScript Guest bindings using your preferred JavaScript package manager: + +> Note: Since most JavaScript package managers are unable to install packages from git monorepos we provide read-only mirrors of each plugin. This makes installation option 2 more ergonomic to use. + +```sh +pnpm add tauri-plugin-positioner +# or +npm add tauri-plugin-positioner +# or +yarn add tauri-plugin-positioner +``` + +Or through git: + +```sh +pnpm add https://github.com/tauri-apps/tauri-plugin-positioner +# or +npm add https://github.com/tauri-apps/tauri-plugin-positioner +# or +yarn add https://github.com/tauri-apps/tauri-plugin-positioner ``` ## Usage +First you need to register the core plugin with Tauri: + +`src-tauri/src/main.rs` +```rust +fn main() { + tauri::Builder::default() + .plugin(tauri_plugin_positioner::init()) + // This is required to get tray-relative positions to work + .on_system_tray_event(|app, event| { + tauri_plugin_positioner::on_tray_event(app, &event); + }) + .run() + .expect("error while running tauri application"); +} +``` + +Afterwards all the plugin's APIs are available through the JavaScript guest bindings: + +```javascript +import { move_window, Position } from 'tauri-plugin-positioner-api' + +move_window(Position.TopRight) ``` +If you only intend on moving the window from rust code, you can import the Window trait extension instead of registering the plugin: + +```rust +use tauri_plugin_positioner::{WindowExt, Position}; + +let mut win = app.get_window("main").unwrap(); +let _ = win.move_window(Position::TopRight); ``` ## Contributing @@ -20,6 +85,7 @@ PRs accepted. Please make sure to read the Contributing Guide before making a pu ## License -Code: (c) 2015 - 2021 - The Tauri Programme within The Commons Conservancy. +Code: (c) 2021 - Jonas Kruckenberg. 2021 - Present - The Tauri Programme within The Commons Conservancy. MIT or MIT/Apache 2.0 where applicable. + diff --git a/plugins/sql/README.md b/plugins/sql/README.md index 8649c739..ee7ef740 100644 --- a/plugins/sql/README.md +++ b/plugins/sql/README.md @@ -1,17 +1,64 @@ ![plugin-sql](banner.png) - +Interface with SQL databases through [sqlx](https://github.com/launchbadge/sqlx). It supports the `sqlite`, `mysql` and `postgres` drivers, enabled by a Cargo feature. ## Install +There are three general methods of installation that we can recommend. + +1. Use crates.io and npm (easiest, and requires you to trust that our publishing pipeline worked) +2. Pull sources directly from Github using git tags / revision hashes (most secure) +3. Git submodule install this repo in your tauri project and then use file protocol to ingest the source (most secure, but inconvenient to use) + +Install the Core plugin by adding the following to your `Cargo.toml` file: + +`src-tauri/Cargo.toml` +```toml +[dependencies.tauri-plugin-sql] +git = "https://github.com/tauri-apps/plugins-workspace" +branch = "dev" +features = ["sqlite"] # or "postgres", or "mysql" ``` +You can install the JavaScript Guest bindings using your preferred JavaScript package manager: + +> Note: Since most JavaScript package managers are unable to install packages from git monorepos we provide read-only mirrors of each plugin. This makes installation option 2 more ergonomic to use. + +```sh +pnpm add https://github.com/tauri-apps/tauri-plugin-sql +# or +npm add https://github.com/tauri-apps/tauri-plugin-sql +# or +yarn add https://github.com/tauri-apps/tauri-plugin-sql ``` ## Usage +First you need to register the core plugin with Tauri: + +`src-tauri/src/main.rs` +```rust +fn main() { + tauri::Builder::default() + .plugin(tauri_plugin_sql::Builder::default()) + .run(tauri::generate_context!()) + .expect("error while running tauri application"); +} ``` +Afterwards all the plugin's APIs are available through the JavaScript guest bindings: + +```javascript +import Database from 'tauri-plugin-sql-api' + +// sqlite. The path is relative to `tauri::api::path::BaseDirectory::App`. +const db = await Database.load('sqlite:test.db') +// mysql +const db = await Database.load('mysql://user:pass@host/database') +// postgres +const db = await Database.load('postgres://postgres:password@localhost/test') + +await db.execute('INSERT INTO ...') ``` ## Contributing @@ -20,6 +67,6 @@ PRs accepted. Please make sure to read the Contributing Guide before making a pu ## License -Code: (c) 2015 - 2021 - The Tauri Programme within The Commons Conservancy. +Code: (c) 2015 - Present - The Tauri Programme within The Commons Conservancy. MIT or MIT/Apache 2.0 where applicable. diff --git a/plugins/store/README.md b/plugins/store/README.md index 8baf2b8e..4276872d 100644 --- a/plugins/store/README.md +++ b/plugins/store/README.md @@ -1,17 +1,60 @@ ![plugin-store](banner.png) - +Simple, persistent key-value store. ## Install +There are three general methods of installation that we can recommend. + +1. Use crates.io and npm (easiest, and requires you to trust that our publishing pipeline worked) +2. Pull sources directly from Github using git tags / revision hashes (most secure) +3. Git submodule install this repo in your tauri project and then use file protocol to ingest the source (most secure, but inconvenient to use) + +Install the Core plugin by adding the following to your `Cargo.toml` file: + +`src-tauri/Cargo.toml` +```toml +[dependencies] +tauri-plugin-store = { git = "https://github.com/tauri-apps/plugins-workspace", branch = "dev" } ``` +You can install the JavaScript Guest bindings using your preferred JavaScript package manager: + +> Note: Since most JavaScript package managers are unable to install packages from git monorepos we provide read-only mirrors of each plugin. This makes installation option 2 more ergonomic to use. + +```sh +pnpm add https://github.com/tauri-apps/tauri-plugin-store +# or +npm add https://github.com/tauri-apps/tauri-plugin-store +# or +yarn add https://github.com/tauri-apps/tauri-plugin-store ``` ## Usage +First you need to register the core plugin with Tauri: + +`src-tauri/src/main.rs` +```rust +fn main() { + tauri::Builder::default() + .plugin(tauri_plugin_store::Builder::default().build()) + .run(tauri::generate_context!()) + .expect("error while running tauri application"); +} ``` +Afterwards all the plugin's APIs are available through the JavaScript guest bindings: + +```javascript +import { Store } from 'tauri-plugin-store-api'; + +const store = new Store('.settings.dat'); + +await store.set('some-key', { value: 5 }); + +const val = await store.get('some-key'); +assert(val, { value: 5 }); ``` ## Contributing @@ -20,6 +63,6 @@ PRs accepted. Please make sure to read the Contributing Guide before making a pu ## License -Code: (c) 2015 - 2021 - The Tauri Programme within The Commons Conservancy. +Code: (c) 2015 - Present - The Tauri Programme within The Commons Conservancy. MIT or MIT/Apache 2.0 where applicable. diff --git a/plugins/stronghold/README.md b/plugins/stronghold/README.md index 0f5158c4..3831aaa8 100644 --- a/plugins/stronghold/README.md +++ b/plugins/stronghold/README.md @@ -1,17 +1,59 @@ ![plugin-stronghold](banner.png) - +Store secrets and keys using the [IOTA Stronghold](https://github.com/iotaledger/stronghold.rs) encrypted database and secure runtime. ## Install +There are three general methods of installation that we can recommend. + +1. Use crates.io and npm (easiest, and requires you to trust that our publishing pipeline worked) +2. Pull sources directly from Github using git tags / revision hashes (most secure) +3. Git submodule install this repo in your tauri project and then use file protocol to ingest the source (most secure, but inconvenient to use) + +Install the Core plugin by adding the following to your `Cargo.toml` file: + +`src-tauri/Cargo.toml` +```toml +[dependencies] +tauri-plugin-stronghold = { git = "https://github.com/tauri-apps/plugins-workspace", branch = "dev" } ``` +You can install the JavaScript Guest bindings using your preferred JavaScript package manager: + +> Note: Since most JavaScript package managers are unable to install packages from git monorepos we provide read-only mirrors of each plugin. This makes installation option 2 more ergonomic to use. + +```sh +pnpm add https://github.com/tauri-apps/tauri-plugin-stronghold +# or +npm add https://github.com/tauri-apps/tauri-plugin-stronghold +# or +yarn add https://github.com/tauri-apps/tauri-plugin-stronghold ``` ## Usage +First you need to register the core plugin with Tauri: + +`src-tauri/src/main.rs` +```rust +fn main() { + tauri::Builder::default() + .plugin(tauri_plugin_stronghold::Builder::new(|password| { + // TODO: hash the password here with e.g. argon2, blake2b or any other secure algorithm + todo!() + }) + .build()) + .run(tauri::generate_context!()) + .expect("error while running tauri application"); +} ``` +Afterwards all the plugin's APIs are available through the JavaScript guest bindings: + +```javascript +import { Stronghold, Location } from 'tauri-plugin-stronghold-api' + +// TODO ``` ## Contributing @@ -20,6 +62,7 @@ PRs accepted. Please make sure to read the Contributing Guide before making a pu ## License -Code: (c) 2015 - 2021 - The Tauri Programme within The Commons Conservancy. +Code: (c) 2015 - Present - The Tauri Programme within The Commons Conservancy. MIT or MIT/Apache 2.0 where applicable. + diff --git a/plugins/upload/README.md b/plugins/upload/README.md index 04bb3400..12bddc7c 100644 --- a/plugins/upload/README.md +++ b/plugins/upload/README.md @@ -1,17 +1,60 @@ ![plugin-upload](banner.png) - +Upload files from disk to a remote server over http. ## Install +There are three general methods of installation that we can recommend. + +1. Use crates.io and npm (easiest, and requires you to trust that our publishing pipeline worked) +2. Pull sources directly from Github using git tags / revision hashes (most secure) +3. Git submodule install this repo in your tauri project and then use file protocol to ingest the source (most secure, but inconvenient to use) + +Install the Core plugin by adding the following to your `Cargo.toml` file: + +`src-tauri/Cargo.toml` +```toml +[dependencies] +tauri-plugin-upload = { git = "https://github.com/tauri-apps/plugins-workspace", branch = "dev" } ``` +You can install the JavaScript Guest bindings using your preferred JavaScript package manager: + +> Note: Since most JavaScript package managers are unable to install packages from git monorepos we provide read-only mirrors of each plugin. This makes installation option 2 more ergonomic to use. + +```sh +pnpm add https://github.com/tauri-apps/tauri-plugin-upload +# or +npm add https://github.com/tauri-apps/tauri-plugin-upload +# or +yarn add https://github.com/tauri-apps/tauri-plugin-upload ``` ## Usage +First you need to register the core plugin with Tauri: + +`src-tauri/src/main.rs` +```rust +fn main() { + tauri::Builder::default() + .plugin(tauri_plugin_upload::init()) + .run(tauri::generate_context!()) + .expect("error while running tauri application"); +} ``` +Afterwards all the plugin's APIs are available through the JavaScript guest bindings: + +```javascript +import { upload } from 'tauri-plugin-upload-api' + +upload( + 'https://example.com/file-upload' + './path/to/my/file.txt' + (progress, total) => console.log(`Downloaded ${progress} of ${total} bytes`) // a callback that will be called with the upload progress + { 'ContentType': 'text/plain' } // optional headers to send with the request +) ``` ## Contributing @@ -20,6 +63,6 @@ PRs accepted. Please make sure to read the Contributing Guide before making a pu ## License -Code: (c) 2015 - 2021 - The Tauri Programme within The Commons Conservancy. +Code: (c) 2015 - Present - The Tauri Programme within The Commons Conservancy. MIT or MIT/Apache 2.0 where applicable. diff --git a/plugins/websocket/README.md b/plugins/websocket/README.md index a864895b..9d1abd6c 100644 --- a/plugins/websocket/README.md +++ b/plugins/websocket/README.md @@ -4,14 +4,56 @@ ## Install +There are three general methods of installation that we can recommend. + +1. Use crates.io and npm (easiest, and requires you to trust that our publishing pipeline worked) +2. Pull sources directly from Github using git tags / revision hashes (most secure) +3. Git submodule install this repo in your tauri project and then use file protocol to ingest the source (most secure, but inconvenient to use) + +Install the Core plugin by adding the following to your `Cargo.toml` file: + +`src-tauri/Cargo.toml` +```toml +[dependencies] +tauri-plugin-websocket = { git = "https://github.com/tauri-apps/plugins-workspace", branch = "dev" } ``` +You can install the JavaScript Guest bindings using your preferred JavaScript package manager: + +> Note: Since most JavaScript package managers are unable to install packages from git monorepos we provide read-only mirrors of each plugin. This makes installation option 2 more ergonomic to use. + +```sh +pnpm add https://github.com/tauri-apps/tauri-plugin-websocket +# or +npm add https://github.com/tauri-apps/tauri-plugin-websocket +# or +yarn add https://github.com/tauri-apps/tauri-plugin-websocket ``` ## Usage +First you need to register the core plugin with Tauri: + +`src-tauri/src/main.rs` +```rust +fn main() { + tauri::Builder::default() + .plugin(tauri_plugin_websocket::init()) + .run(tauri::generate_context!()) + .expect("error while running tauri application"); +} ``` +Afterwards all the plugin's APIs are available through the JavaScript guest bindings: + +```javascript +import { WebSocket } from 'tauri-plugin-websocket-api' + +const ws = await WebSocket.connect('wss://example.com') + +await ws.send('Hello World') + +await ws.disconnect() ``` ## Contributing @@ -20,6 +62,6 @@ PRs accepted. Please make sure to read the Contributing Guide before making a pu ## License -Code: (c) 2015 - 2021 - The Tauri Programme within The Commons Conservancy. +Code: (c) 2015 - Present - The Tauri Programme within The Commons Conservancy. MIT or MIT/Apache 2.0 where applicable. diff --git a/plugins/window-state/README.md b/plugins/window-state/README.md index 3f2619a2..1ef7019d 100644 --- a/plugins/window-state/README.md +++ b/plugins/window-state/README.md @@ -1,17 +1,55 @@ ![plugin-window-state](banner.png) +Save window positions and sizse and restore them when the app is reopened. + ## Install -``` +There are three general methods of installation that we can recommend. + +1. Use crates.io and npm (easiest, and requires you to trust that our publishing pipeline worked) +2. Pull sources directly from Github using git tags / revision hashes (most secure) +3. Git submodule install this repo in your tauri project and then use file protocol to ingest the source (most secure, but inconvenient to use) +Install the Core plugin by adding the following to your `Cargo.toml` file: + +`src-tauri/Cargo.toml` +```toml +[dependencies] +tauri-plugin-window-state = { git = "https://github.com/tauri-apps/plugins-workspace", branch = "dev" } ``` ## Usage +First you need to register the core plugin with Tauri: + +`src-tauri/src/main.rs` +```rust +fn main() { + tauri::Builder::default() + .plugin(tauri_plugin_window_state::Builder::default().build()) + .run(tauri::generate_context!()) + .expect("error while running tauri application"); +} ``` +Afterwards all windows will remember their state when the app is being closed and will restore to their previous state on the next launch. + +Optionally you can also tell the plugin to save the state of all open window to disk my using the `save_window_state()` method exposed by the `AppHandleExt` trait: +```rust +use tauri_plugin_window_state::AppHandleExt; + +// `tauri::AppHandle` now has the following additional method +app.save_window_state(); // will save the state of all open windows to disk +``` + +To manually restore a windows state from disk you can call the `restore_state()` method exposed by the `WindowExt` trait: +```rust +use tauri_plugin_window_state::{WindowExt, ShowMode}; + +// all `Window` types now have the following additional method +window.restore_state(ShowMode::LastSaved); // will restore the windows state from disk ``` ## Contributing @@ -20,6 +58,6 @@ PRs accepted. Please make sure to read the Contributing Guide before making a pu ## License -Code: (c) 2015 - 2021 - The Tauri Programme within The Commons Conservancy. +Code: (c) 2015 - Present - The Tauri Programme within The Commons Conservancy. MIT or MIT/Apache 2.0 where applicable. diff --git a/shared/template/README.md b/shared/template/README.md index 97196018..5823ab98 100644 --- a/shared/template/README.md +++ b/shared/template/README.md @@ -1,17 +1,53 @@ -{{name}} +![{{plugin name}}](banner.jpg) ## Install +There are three general methods of installation that we can recommend. + +1. Use crates.io and npm (easiest, and requires you to trust that our publishing pipeline worked) +2. Pull sources directly from Github using git tags / revision hashes (most secure) +3. Git submodule install this repo in your tauri project and then use file protocol to ingest the source (most secure, but inconvenient to use) + +Install the Core plugin by adding the following to your `Cargo.toml` file: + +`src-tauri/Cargo.toml` +```toml +[dependencies] + = { git = "https://github.com/tauri-apps/plugins-workspace", branch = "dev" } ``` +You can install the JavaScript Guest bindings using your preferred JavaScript package manager: + +> Note: Since most JavaScript package managers are unable to install packages from git monorepos we provide read-only mirrors of each plugin. This makes installation option 2 more ergonomic to use. + +```sh +pnpm add +# or +npm add +# or +yarn add ``` ## Usage +First you need to register the core plugin with Tauri: + +`src-tauri/src/main.rs` +```rust +fn main() { + tauri::Builder::default() + .plugin() + .run(tauri::generate_context!()) + .expect("error while running tauri application"); +} ``` +Afterwards all the plugin's APIs are available through the JavaScript guest bindings: + +```javascript + ``` ## Contributing @@ -20,6 +56,6 @@ PRs accepted. Please make sure to read the Contributing Guide before making a pu ## License -Code: (c) 2015 - 2021 - The Tauri Programme within The Commons Conservancy. +Code: (c) 2015 - Present - The Tauri Programme within The Commons Conservancy. MIT or MIT/Apache 2.0 where applicable.