Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge pull request #76 from oscartbeaumont/better-readme-docs
Better readme docs
- Loading branch information
Showing
3 changed files
with
224 additions
and
148 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,80 @@ | ||
| # v1 | ||
|
|
||
| This is the stable version of `tauri-specta` that uses Specta v1. | ||
|
|
||
| ## 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"); |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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") | ||
| ``` |