feat: added notifications guide #1379
There are no files selected for viewing
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,10 +1,160 @@ | ||
| --- | ||
| title: Notifications | ||
| description: Send native notifications to the user. | ||
| --- | ||
|
|
||
| import PluginBreadcrumb from '@components/PluginBreadcrumb.astro'; | ||
| import { Tabs, TabItem } from '@astrojs/starlight/components'; | ||
| import CommandTabs from '@components/CommandTabs.astro'; | ||
| import Stub from '@components/Stub.astro'; | ||
|
|
||
| <PluginBreadcrumb | ||
| version="v2.0.0-alpha.2" | ||
| github="https://github.com/tauri-apps/plugins-workspace/tree/v2/plugins/notification" | ||
| npm="https://www.npmjs.com/package/@tauri-apps/plugin-notification" | ||
| cratesio="https://crates.io/crates/tauri-plugin-notification" | ||
| jsApi="/2/reference/js/notification" | ||
| docsrs="https://docs.rs/tauri-plugin-notification/2.0.0-alpha.2/tauri_plugin_notification/" | ||
| /> | ||
|
|
||
| Send native notifications to your user using the notification plugin. | ||
|
|
||
| ## Setup | ||
|
|
||
| Install the notifications plugin to get started. | ||
|
|
||
| <Tabs> | ||
| <TabItem label="Automatic"> | ||
|
|
||
| 1. Use your project's package manager to add the dependency: | ||
|
|
||
| <CommandTabs npm="npm run tauri plugin add notification" | ||
| yarn="yarn run tauri plugin add notification" | ||
| pnpm="pnpm tauri plugin add notification" | ||
| cargo="cargo tauri plugin add notification" /> | ||
|
|
||
| 2. Modify `lib.rs` to initialize the plugin: | ||
|
|
||
| {/* TODO: Revise once https://github.com/tauri-apps/tauri/issues/7696 is in */} | ||
|
|
||
| ```rust | ||
| #[cfg_attr(mobile, tauri::mobile_entry_point)] | ||
| pub fn run() { | ||
| tauri::Builder::default() | ||
| // Initialize the plugin | ||
| .plugin(tauri_plugin_notification::init()) | ||
| .run(tauri::generate_context!()) | ||
| .expect("error while running tauri application"); | ||
| } | ||
| ``` | ||
|
|
||
| </TabItem> | ||
| <TabItem label="Manual"> | ||
|
|
||
| 1. Run `cargo add tauri-plugin-notification` to add the plugin to the project's dependencies in `Cargo.toml`. | ||
|
|
||
| 2. Modify `lib.rs` to initialize the plugin: | ||
|
|
||
| ```rust | ||
| // lib.rs | ||
| #[cfg_attr(mobile, tauri::mobile_entry_point)] | ||
| pub fn run() { | ||
| tauri::Builder::default() | ||
| // Initialize the plugin | ||
| .plugin(tauri_plugin_notification::init()) | ||
| .run(tauri::generate_context!()) | ||
| .expect("error while running tauri application"); | ||
| } | ||
| ``` | ||
|
|
||
| 3. If you'd like to use notifications in JavaScript then install the npm package as well: | ||
|
|
||
| <CommandTabs | ||
| npm="npm install @tauri-apps/plugin-notification" | ||
| yarn="yarn add @tauri-apps/plugin-notification" | ||
| pnpm="pnpm add @tauri-apps/plugin-notification" | ||
| /> | ||
|
|
||
| </TabItem> | ||
|
|
||
| </Tabs> | ||
|
|
||
| ## Usage | ||
|
|
||
| Here are a few examples of how to use the notification plugin: | ||
|
|
||
| - [Sent notification to users](#send-notification) | ||
| - [Add an action to a notification](#actions) | ||
| - [Add an attachment to a notification](#attachments) | ||
| - [Send a notification in a specific channel](#channels) | ||
|
|
||
| {/* TODO: Link to which language to use, frontend vs. backend guide when it's made */} | ||
|
|
||
| The notification plugin is available in both JavaScript and Rust. | ||
|
|
||
| ### Send Notification | ||
|
|
||
| {/* TODO: Demo component */} | ||
|
|
||
| Follow these steps to send a notification: | ||
|
|
||
| 1. Check if permission is granted | ||
| 2. Request permission if not granted | ||
| 3. Send the notification | ||
|
|
||
| <Tabs> | ||
| <TabItem label="JavaScript"> | ||
|
|
||
| ```js | ||
| import { | ||
| isPermissionGranted, | ||
| requestPermission, | ||
| sendNotification, | ||
| } from '@tauri-apps/plugin-notification'; | ||
|
|
||
| // Do you have permission to send a notification? | ||
| let permissionGranted = await isPermissionGranted(); | ||
|
|
||
| // If not we need to request it | ||
| if (!permissionGranted) { | ||
| const permission = await requestPermission(); | ||
| permissionGranted = permission === 'granted'; | ||
| } | ||
|
|
||
| // Once permission has been granted we can send the notification | ||
| if (permissionGranted) { | ||
| sendNotification({ title: 'Tauri', body: 'Tauri is awesome!' }); | ||
| } | ||
| ``` | ||
|
|
||
| </TabItem> | ||
| <TabItem label="Rust"> | ||
|
|
||
| {/* TODO: */} | ||
|
|
||
| <Stub /> | ||
|
|
||
| </TabItem> | ||
| </Tabs> | ||
|
|
||
| ### Actions | ||
|
There was a problem hiding this comment. @simonhyll what do you think about this sort of structure? I think this could go a really long way to give link-able places for support There was a problem hiding this comment. I would put Not sure what Actions, Attachments or Channels are for? Is it to explain notification concepts or are they general sections that all recipes could have? Options I assume is just a simplified version of what you'd find in the actual API. As long as they aren't too wordy and are copy-paste friendly I'm probably fine with them. I'm still not overly fond of the terminology of Javascript vs Rust since we should really also have the Rust version avilable using something like Jonas' tauri-sys crate so that the Rust frameworks also get included, because with just JS and Rust (backend) we're kinda leaving them hanging, and I don't see a nice way of adding them without ending up with really annoying names. I'd prefer it if we write about Frontend and Backend as core concepts of Tauri and if people skipped that part then it's not really our problem they refused to read what is almost literally called "the only stuff that's non-optional for you to skip reading". I could also accept Javascript, Rust and Backend I guess because then all frontend languages get included plus one for the backend, but even that isn't completely future proof since we have plans for language bindings at some point. In the end I defer to your wisdom on the docs in general, so feel free to overrule me on basically anything 😅 There was a problem hiding this comment. Note that I read your comments from the bottom to the top and just saw your comment earlier explaining what you meant with Actions, Attachments etc. I'm tired, brain no work 😅 There was a problem hiding this comment. Open to whatever you feel would be best for security considerations. I figured if there was anything in-depth that would link out either externally or to a concept and maybe not include it in the guide (unless it really is only very specific to that guide/feature). Actions, Attachment, Channels, and Options are part of the plugins APIs, so really just more copy-pasteable examples:
RE: Frontend/backend/rust/js how about we put some data-driven decisions in practice and make a poll we can post to Twitter, Discord, and Mastodon and see what comes out?
Literally have never heard of that until today (looks cool!): https://github.com/JonasKruckenberg/tauri-sys. I do wonder if this is really a more advanced-level usage that's outside of the target audience (i.e. beginners) for docs? A piece that maybe just fell in place for me: do you not like "Rust" because you can have both a Rust frontend (yew, sycamore, etc.) and a Rust backend (application logic, what you're truly referring to as backend) in the same app? Because if that's the case then it just clicked for me and your points are a lot more clear to me now. There was a problem hiding this comment.
I mean we've only had like a million comments on this one poor PR the past few days 😅 There was a problem hiding this comment. Yea exactly, we want to support our buddies over at the Rust based frontend frameworks, so saying "rust" just for the backend isnt as inclusive And tauri-sys I would say is the more beginner friendly option than the alternative if you develop using e.g. Yew Leptos or Sycamore. You dont even want to know what the alternative looks like, Jonas really did make aomething awesome and at some point we might wanna make it the actual official approach and "take over" his project. It's kind alike the official JS API but for Rust There was a problem hiding this comment. Could you give some examples of how it's different to use the Rust API in Rust frontend code vs. Rust backend code? Might be better to do it outside of the context of notifications where it's a more practical example, but I think that context is what I'm missing. Keep in mind that for now we're only covering how to do things with the first-party APIs (I don't think you were thinking of putting I do wonder if "covering all the ways to consume the API" is a similar rabbit hole we got into with "cover all the different JS frontend frameworks"? And if we're wanting to say "here's how you do it in x, then here's a common guide on using Tauri within the context of that". But I doubt we want to NEED to document all of these combinations in every single feature/guide 🤔 There was a problem hiding this comment. Even if we dont do tauri-sys specifically skipping Rust entirely will leave our beloved rustaceans behind. Using tauri-sys isnt quite the same thing as the framework rabbit hole imo, but if we skip it we should at least offer a "vanilla Rust" example same as we do with vanilla JS There was a problem hiding this comment. I agree, but we need the dev team to either do that upstream if it doesn't already, or they need to provide the docs and examples to help us write the guides for it. Right now I didn't find any examples for the Rust side of things to be able to fill it out. |
||
|
|
||
| {/* TODO: */} | ||
|
|
||
| <Stub /> | ||
|
|
||
| ### Attachments | ||
|
|
||
| {/* TODO: */} | ||
|
|
||
| <Stub /> | ||
|
|
||
| ### Channels | ||
|
|
||
| {/* TODO: */} | ||
|
|
||
| <Stub /> | ||
|
|
||
| ## Security Considerations | ||
|
|
||
| Aside from normal sanitization procedures of user input there are currently no known security considerations. | ||
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I fully realise this goes against my own UX principals so feel free to rake me across the coals if you don't think it works here @simonhyll 😅
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I should screenshot this and post on the Astro server 😂
It certainly makes more sense to do it like that if you structure things without the separated Frontend and Backend sections. As I see it it's not actually nested tabs, it's just the ability to switch which package manager you wanna use
Speaking of choosing your package manager, what if when the user switches tabs we save that to LocalStorage so all CommandTabs default to the last one they picked?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Please do, I'm sure Chris would get a kick out of it 😆
I believe that's what they've discussed in withastro/starlight#462. If you get bored and want to dive into Starlight land I'm sure HiDeoo would love to have a contribution based on his issue.