From acd25c6642cc7faa2ad192a6bf41b80d1c0b18fa Mon Sep 17 00:00:00 2001 From: Brendan Allan Date: Sat, 24 Feb 2024 10:19:50 +0800 Subject: [PATCH 1/5] better --- README.md | 151 ++--------------------------------------------------- docs/v1.md | 83 +++++++++++++++++++++++++++++ docs/v2.md | 137 ++++++++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 225 insertions(+), 146 deletions(-) create mode 100644 docs/v1.md create mode 100644 docs/v2.md diff --git a/README.md b/README.md index 52c150d..6ee60f9 100644 --- a/README.md +++ b/README.md @@ -12,155 +12,14 @@
-> This branch contains the code for tauri-specta v2. You can check the [v1.0.2 git tag](https://github.com/oscartbeaumont/tauri-specta/tree/v1.0.2) for the v1 code. +This branch contains the code for tauri-specta v2. You can check the [v1.0.2 git tag](https://github.com/oscartbeaumont/tauri-specta/tree/v1.0.2) for the v1 code. -## Install +## Getting Started -## Specta v1 - -```bash -cargo add specta -cargo add tauri-specta --features javascript,typescript -``` - -## Specta v2 - -Specta v2 hasn't officially launched yet but it can be used through the release candidate (`rc`) versions. - -You must **ensure** you lock your Specta version to avoid breaking changes. - -```bash -cargo add specta@=2.0.0-rc.7 -cargo add tauri-specta@=2.0.0-rc.4 --features javascript,typescript -``` - -## Adding Specta to custom types - -```rust -use specta::Type; -use serde::{Deserialize, Serialize}; - -// The `specta::Type` macro allows us to understand your types -// We implement `specta::Type` on primitive types for you. -// If you want to use a type from an external crate you may need to enable the feature on Specta. -#[derive(Serialize, Type)] -pub struct MyCustomReturnType { - pub some_field: String, -} - -#[derive(Deserialize, Type)] -pub struct MyCustomArgumentType { - pub foo: String, - pub bar: i32, -} -``` - -## Annotate your Tauri commands with Specta - -```rust -#[tauri::command] -#[specta::specta] // <-- This bit here -fn greet3() -> MyCustomReturnType { - MyCustomReturnType { - some_field: "Hello World".into(), - } -} - -#[tauri::command] -#[specta::specta] // <-- This bit here -fn greet(name: String) -> String { - format!("Hello {name}!") -} -``` - -## Export your bindings - -```rust -use specta::collect_types; -use tauri_specta::{ts, js}; - -// this example exports your types on startup when in debug mode. You can do whatever. - -fn main() { - let specta_builder = { - // You can use `tauri_specta::js::builder` for exporting JS Doc instead of Typescript!` - let specta_builder = tauri_specta::ts::builder() - .commands(tauri_specta::collect_commands![greet, greet2, greet3 ]); // <- Each of your comments - - - #[cfg(debug_assertions)] // <- Only export on non-release builds - let specta_builder = specta_builder.path("../src/bindings.ts"); - - specta_builder.into_plugin() - }; - - tauri::Builder::default() - .plugin(specta_builder) - .run(tauri::generate_context!()) - .expect("error while running tauri application"); -} -``` - -## Usage on frontend - -```ts -import * as commands from "./bindings"; // This should point to the file we export from Rust - -await commands.greet("Brendan"); -``` - -## Events - -> To use Events you must be using [Specta v2 and Tauri Specta v2](#specta-v2). - -Firstly you have to define your event types. You can add as many of these as you want. - -```rust -#[derive(Debug, Clone, Serialize, Deserialize, specta::Type, tauri_specta::Event)] -pub struct DemoEvent(String); -``` - -Next you must add it to the builder like the following: - -```rust -let specta_builder = ts::builder() - .events(tauri_specta::collect_events![DemoEvent]); // This should contain all your events. -``` - -Then it can be used in Rust like the following: - -```rust -tauri::Builder::default() - .setup(|app| { - let handle = app.handle(); - - DemoEvent::listen_global(&handle, |event| { - dbg!(event.payload); - }); - - DemoEvent("Test".to_string()).emit_all(&handle).unwrap(); - }); -``` - -and it can be used in TS like the following: - -```ts -import { commands, events } from "./bindings"; -import { appWindow } from "@tauri-apps/api/window"; - -// For all windows -events.demoEvent.listen((e) => console.log(e)); - -// For a single window -events.demoEvent(appWindow).listen((e) => console.log(e)); - -// Emit to the backend and all windows -await events.demoEvent.emit("Test") - -// Emit to a window -await events.demoEvent(appWindow).emit("Test") -``` +For most use cases, you'll probably want to use [v1](./docs/v1.md), which is stable. +You can also use [v2](./docs/v2.md) which supports generating types for events and utilises Specta v2, +but both it and Specta v2 are still in development. ## Known limitations diff --git a/docs/v1.md b/docs/v1.md new file mode 100644 index 0000000..ecdeec1 --- /dev/null +++ b/docs/v1.md @@ -0,0 +1,83 @@ +# v1 + +This is the stable version of `tauri-specta` that uses Specta v1. + +docs.rs + + +## Install + +```bash +cargo add specta +cargo add tauri-specta --features javascript,typescript +``` + +## Adding Specta to custom types + +```rust +use specta::Type; +use serde::{Deserialize, Serialize}; + +// The `specta::Type` macro allows us to understand your types +// We implement `specta::Type` on primitive types for you. +// If you want to use a type from an external crate you may need to enable the feature on Specta. +#[derive(Serialize, Type)] +pub struct MyCustomReturnType { + pub some_field: String, +} + +#[derive(Deserialize, Type)] +pub struct MyCustomArgumentType { + pub foo: String, + pub bar: i32, +} +``` + +## Annotate your Tauri commands with Specta + +```rust +#[tauri::command] +#[specta::specta] // <-- This bit here +fn greet3() -> MyCustomReturnType { + MyCustomReturnType { + some_field: "Hello World".into(), + } +} + +#[tauri::command] +#[specta::specta] // <-- This bit here +fn greet(name: String) -> String { + format!("Hello {name}!") +} +``` + +## Export your bindings + +```rust +use specta::collect_types; +use tauri_specta::{ts, js}; + +// this example exports your types on startup when in debug mode or in a unit test. You can do whatever. + +fn main() { + #[cfg(debug_assertions)] + ts::export(collect_types![greet, greet2, greet3], "../src/bindings.ts").unwrap(); + + // or export to JS with JSDoc + #[cfg(debug_assertions)] + js::export(collect_types![greet, greet2, greet3], "../src/bindings.js").unwrap(); +} + +#[test] +fn export_bindings() { + ts::export(collect_types![greet, greet2, greet3], "../src/bindings.ts").unwrap(); + js::export(collect_types![greet, greet2, greet3], "../src/bindings.js").unwrap(); +} +``` + +## Usage on frontend + +```ts +import * as commands from "./bindings"; // This should point to the file we export from Rust + +await commands.greet("Brendan"); diff --git a/docs/v2.md b/docs/v2.md new file mode 100644 index 0000000..15a545a --- /dev/null +++ b/docs/v2.md @@ -0,0 +1,137 @@ +# v2 + +`tauri-specta` v2 has more features than v1, but depends on Specta v2 which is not yet stable. + +You must **ensure** you lock your Specta version to avoid breaking changes. + +```bash +cargo add specta@=2.0.0-rc.7 +cargo add tauri-specta@=2.0.0-rc.4 --features javascript,typescript +``` + +## Adding Specta to custom types + +```rust +use specta::Type; +use serde::{Deserialize, Serialize}; + +// The `specta::Type` macro allows us to understand your types +// We implement `specta::Type` on primitive types for you. +// If you want to use a type from an external crate you may need to enable the feature on Specta. +#[derive(Serialize, Type)] +pub struct MyCustomReturnType { + pub some_field: String, +} + +#[derive(Deserialize, Type)] +pub struct MyCustomArgumentType { + pub foo: String, + pub bar: i32, +} +``` + +## Annotate your Tauri commands with Specta + +```rust +#[tauri::command] +#[specta::specta] // <-- This bit here +fn greet3() -> MyCustomReturnType { + MyCustomReturnType { + some_field: "Hello World".into(), + } +} + +#[tauri::command] +#[specta::specta] // <-- This bit here +fn greet(name: String) -> String { + format!("Hello {name}!") +} +``` + +## Export your bindings + +```rust +use specta::collect_types; +use tauri_specta::{ts, js}; + +// this example exports your types on startup when in debug mode. You can do whatever. + +fn main() { + let specta_builder = { + // You can use `tauri_specta::js::builder` for exporting JS Doc instead of Typescript!` + let specta_builder = tauri_specta::ts::builder() + .commands(tauri_specta::collect_commands![greet, greet2, greet3 ]); // <- Each of your comments + + + #[cfg(debug_assertions)] // <- Only export on non-release builds + let specta_builder = specta_builder.path("../src/bindings.ts"); + + specta_builder.into_plugin() + }; + + tauri::Builder::default() + .plugin(specta_builder) + .run(tauri::generate_context!()) + .expect("error while running tauri application"); +} +``` + +## Usage on frontend + +```ts +import * as commands from "./bindings"; // This should point to the file we export from Rust + +await commands.greet("Brendan"); +``` + +## Events + +> To use Events you must be using [Specta v2 and Tauri Specta v2](#specta-v2). + +Firstly you have to define your event types. You can add as many of these as you want. + +```rust +#[derive(Debug, Clone, Serialize, Deserialize, specta::Type, tauri_specta::Event)] +pub struct DemoEvent(String); +``` + +Next you must add it to the builder like the following: + +```rust +let specta_builder = ts::builder() + .events(tauri_specta::collect_events![DemoEvent]); // This should contain all your events. +``` + +Then it can be used in Rust like the following: + +```rust +tauri::Builder::default() + .setup(|app| { + let handle = app.handle(); + + DemoEvent::listen_global(&handle, |event| { + dbg!(event.payload); + }); + + DemoEvent("Test".to_string()).emit_all(&handle).unwrap(); + }); +``` + +and it can be used in TS like the following: + +```ts +import { commands, events } from "./bindings"; +import { appWindow } from "@tauri-apps/api/window"; + +// For all windows +events.demoEvent.listen((e) => console.log(e)); + +// For a single window +events.demoEvent(appWindow).listen((e) => console.log(e)); + +// Emit to the backend and all windows +await events.demoEvent.emit("Test") + +// Emit to a window +await events.demoEvent(appWindow).emit("Test") +``` From b5538d67f39980b415f6e96e57b5e4455a92ed03 Mon Sep 17 00:00:00 2001 From: Brendan Allan Date: Sat, 24 Feb 2024 10:23:01 +0800 Subject: [PATCH 2/5] badge --- docs/v2.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/v2.md b/docs/v2.md index 15a545a..cb48fd3 100644 --- a/docs/v2.md +++ b/docs/v2.md @@ -9,6 +9,8 @@ cargo add specta@=2.0.0-rc.7 cargo add tauri-specta@=2.0.0-rc.4 --features javascript,typescript ``` +docs.rs + ## Adding Specta to custom types ```rust From c11e4bf47cb1cc66b37f4ee25fb3509e07694535 Mon Sep 17 00:00:00 2001 From: Brendan Allan Date: Sat, 24 Feb 2024 10:23:25 +0800 Subject: [PATCH 3/5] better badge --- docs/v1.md | 4 ++-- docs/v2.md | 4 ++-- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/v1.md b/docs/v1.md index ecdeec1..018c950 100644 --- a/docs/v1.md +++ b/docs/v1.md @@ -1,8 +1,8 @@ # v1 -This is the stable version of `tauri-specta` that uses Specta v1. +docs.rs -docs.rs +This is the stable version of `tauri-specta` that uses Specta v1. ## Install diff --git a/docs/v2.md b/docs/v2.md index cb48fd3..57f4689 100644 --- a/docs/v2.md +++ b/docs/v2.md @@ -1,5 +1,7 @@ # v2 +docs.rs + `tauri-specta` v2 has more features than v1, but depends on Specta v2 which is not yet stable. You must **ensure** you lock your Specta version to avoid breaking changes. @@ -9,8 +11,6 @@ cargo add specta@=2.0.0-rc.7 cargo add tauri-specta@=2.0.0-rc.4 --features javascript,typescript ``` -docs.rs - ## Adding Specta to custom types ```rust From 5caf4ecfef71c2129fb982c685df3db33967a1df Mon Sep 17 00:00:00 2001 From: Brendan Allan Date: Sat, 24 Feb 2024 10:27:59 +0800 Subject: [PATCH 4/5] yea idk --- README.md | 2 -- docs/v1.md | 3 --- docs/v2.md | 2 -- 3 files changed, 7 deletions(-) diff --git a/README.md b/README.md index 6ee60f9..dff5be9 100644 --- a/README.md +++ b/README.md @@ -3,10 +3,8 @@

Tauri Specta

Typesafe Tauri commands

Discord - Crates.io crates.io - docs.rs License diff --git a/docs/v1.md b/docs/v1.md index 018c950..3e36d89 100644 --- a/docs/v1.md +++ b/docs/v1.md @@ -1,10 +1,7 @@ # v1 -docs.rs - This is the stable version of `tauri-specta` that uses Specta v1. - ## Install ```bash diff --git a/docs/v2.md b/docs/v2.md index 57f4689..15a545a 100644 --- a/docs/v2.md +++ b/docs/v2.md @@ -1,7 +1,5 @@ # v2 -docs.rs - `tauri-specta` v2 has more features than v1, but depends on Specta v2 which is not yet stable. You must **ensure** you lock your Specta version to avoid breaking changes. From 5eb993ccfabccd4847fb4438f76a5ac520ceb1a5 Mon Sep 17 00:00:00 2001 From: Brendan Allan Date: Sat, 24 Feb 2024 10:30:01 +0800 Subject: [PATCH 5/5] explain where examples are --- README.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index dff5be9..c212182 100644 --- a/README.md +++ b/README.md @@ -10,7 +10,9 @@
-This branch contains the code for tauri-specta v2. You can check the [v1.0.2 git tag](https://github.com/oscartbeaumont/tauri-specta/tree/v1.0.2) for the v1 code. +This branch contains code + examples for tauri-specta v2. +You can check the [v1.0.2 git tag](https://github.com/oscartbeaumont/tauri-specta/tree/v1.0.2) +for the v1 code + examples. ## Getting Started