mirror of
https://github.com/tauri-apps/plugins-workspace.git
synced 2026-06-06 13:53:54 +02:00
docs: update README.md and remove allowlist information (#381)
This commit is contained in:
Lucas Fernandes Nogueira
committed by
GitHub
GitHub
parent
d677f73495
commit
f4069f5588
+13
-3
@@ -1,6 +1,6 @@
|
||||
|
||||
# Shell
|
||||
|
||||
<!-- description -->
|
||||
Access the system shell. Allows you to spawn child processes and manage files and URLs using their default application.
|
||||
|
||||
## Install
|
||||
|
||||
@@ -18,6 +18,8 @@ Install the Core plugin by adding the following to your `Cargo.toml` file:
|
||||
|
||||
```toml
|
||||
[dependencies]
|
||||
tauri-plugin-shell = "2.0.0-alpha"
|
||||
# alternatively with Git:
|
||||
tauri-plugin-shell = { git = "https://github.com/tauri-apps/plugins-workspace", branch = "v2" }
|
||||
```
|
||||
|
||||
@@ -26,6 +28,13 @@ You can install the JavaScript Guest bindings using your preferred JavaScript pa
|
||||
> 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-apps/plugin-shell
|
||||
# or
|
||||
npm add @tauri-apps/plugin-shell
|
||||
# or
|
||||
yarn add @tauri-apps/plugin-shell
|
||||
|
||||
# alternatively with Git:
|
||||
pnpm add https://github.com/tauri-apps/tauri-plugin-shell#v2
|
||||
# or
|
||||
npm add https://github.com/tauri-apps/tauri-plugin-shell#v2
|
||||
@@ -51,7 +60,8 @@ fn main() {
|
||||
Afterwards all the plugin's APIs are available through the JavaScript guest bindings:
|
||||
|
||||
```javascript
|
||||
|
||||
import { Command } from "@tauri-apps/plugin-shell";
|
||||
Command.create("git", ["commit", "-m", "the commit message"]);
|
||||
```
|
||||
|
||||
## Contributing
|
||||
|
||||
@@ -6,36 +6,19 @@
|
||||
* Access the system shell.
|
||||
* Allows you to spawn child processes and manage files and URLs using their default application.
|
||||
*
|
||||
* The APIs must be added to [`tauri.allowlist.shell`](https://tauri.app/v1/api/config/#allowlistconfig.shell) in `tauri.conf.json`:
|
||||
* ```json
|
||||
* {
|
||||
* "tauri": {
|
||||
* "allowlist": {
|
||||
* "shell": {
|
||||
* "all": true, // enable all shell APIs
|
||||
* "execute": true, // enable process spawn APIs
|
||||
* "sidecar": true, // enable spawning sidecars
|
||||
* "open": true // enable opening files/URLs using the default program
|
||||
* }
|
||||
* }
|
||||
* }
|
||||
* }
|
||||
* ```
|
||||
* It is recommended to allowlist only the APIs you use for optimal bundle size and security.
|
||||
*
|
||||
* ## Security
|
||||
*
|
||||
* This API has a scope configuration that forces you to restrict the programs and arguments that can be used.
|
||||
*
|
||||
* ### Restricting access to the {@link open | `open`} API
|
||||
*
|
||||
* On the allowlist, `open: true` means that the {@link open} API can be used with any URL,
|
||||
* On the configuration object, `open: true` means that the {@link open} API can be used with any URL,
|
||||
* as the argument is validated with the `^((mailto:\w+)|(tel:\w+)|(https?://\w+)).+` regex.
|
||||
* You can change that regex by changing the boolean value to a string, e.g. `open: ^https://github.com/`.
|
||||
*
|
||||
* ### Restricting access to the {@link Command | `Command`} APIs
|
||||
*
|
||||
* The `shell` allowlist object has a `scope` field that defines an array of CLIs that can be used.
|
||||
* The plugin configuration object has a `scope` field that defines an array of CLIs that can be used.
|
||||
* Each CLI is a configuration object `{ name: string, cmd: string, sidecar?: bool, args?: boolean | Arg[] }`.
|
||||
*
|
||||
* - `name`: the unique identifier of the command, passed to the {@link Command.create | Command.create function}.
|
||||
@@ -55,13 +38,17 @@
|
||||
* Configuration:
|
||||
* ```json
|
||||
* {
|
||||
* "scope": [
|
||||
* {
|
||||
* "name": "run-git-commit",
|
||||
* "cmd": "git",
|
||||
* "args": ["commit", "-m", { "validator": "\\S+" }]
|
||||
* "plugins": {
|
||||
* "shell": {
|
||||
* "scope": [
|
||||
* {
|
||||
* "name": "run-git-commit",
|
||||
* "cmd": "git",
|
||||
* "args": ["commit", "-m", { "validator": "\\S+" }]
|
||||
* }
|
||||
* ]
|
||||
* }
|
||||
* ]
|
||||
* }
|
||||
* }
|
||||
* ```
|
||||
* Usage:
|
||||
@@ -425,7 +412,7 @@ class Command<O extends IOPayload> extends EventEmitter<CommandEvents> {
|
||||
* Creates a new `Command` instance.
|
||||
*
|
||||
* @param program The program name to execute.
|
||||
* It must be configured on `tauri.conf.json > tauri > allowlist > shell > scope`.
|
||||
* It must be configured on `tauri.conf.json > plugins > shell > scope`.
|
||||
* @param args Program arguments.
|
||||
* @param options Spawn options.
|
||||
*/
|
||||
@@ -462,7 +449,7 @@ class Command<O extends IOPayload> extends EventEmitter<CommandEvents> {
|
||||
* ```
|
||||
*
|
||||
* @param program The program to execute.
|
||||
* It must be configured on `tauri.conf.json > tauri > allowlist > shell > scope`.
|
||||
* It must be configured on `tauri.conf.json > plugins > shell > scope`.
|
||||
*/
|
||||
static create<O extends IOPayload>(
|
||||
program: string,
|
||||
@@ -494,7 +481,7 @@ class Command<O extends IOPayload> extends EventEmitter<CommandEvents> {
|
||||
* ```
|
||||
*
|
||||
* @param program The program to execute.
|
||||
* It must be configured on `tauri.conf.json > tauri > allowlist > shell > scope`.
|
||||
* It must be configured on `tauri.conf.json > plugins > shell > scope`.
|
||||
*/
|
||||
static sidecar<O extends IOPayload>(
|
||||
program: string,
|
||||
@@ -634,7 +621,7 @@ type CommandEvent<O extends IOPayload> =
|
||||
* ```
|
||||
*
|
||||
* @param path The path or URL to open.
|
||||
* This value is matched against the string regex defined on `tauri.conf.json > tauri > allowlist > shell > open`,
|
||||
* This value is matched against the string regex defined on `tauri.conf.json > plugins > shell > open`,
|
||||
* which defaults to `^((mailto:\w+)|(tel:\w+)|(https?://\w+)).+`.
|
||||
* @param openWith The app to open the file or URL with.
|
||||
* Defaults to the system default application for the specified path type.
|
||||
|
||||
@@ -2,9 +2,7 @@ use std::path::PathBuf;
|
||||
|
||||
use serde::{de::Error as DeError, Deserialize, Deserializer};
|
||||
|
||||
/// Allowlist for the shell APIs.
|
||||
///
|
||||
/// See more: https://tauri.app/v1/api/config#shellallowlistconfig
|
||||
/// Configuration for the shell plugin.
|
||||
#[derive(Debug, Default, PartialEq, Eq, Clone, Deserialize)]
|
||||
#[serde(rename_all = "camelCase", deny_unknown_fields)]
|
||||
pub struct Config {
|
||||
|
||||
@@ -104,7 +104,7 @@ impl Program {
|
||||
/// Opens path or URL with the program specified in `with`, or system default if `None`.
|
||||
///
|
||||
/// The path will be matched against the shell open validation regex, defaulting to `^((mailto:\w+)|(tel:\w+)|(https?://\w+)).+`.
|
||||
/// A custom validation regex may be supplied in the config in `tauri > allowlist > scope > open`.
|
||||
/// A custom validation regex may be supplied in the config in `plugins > shell > scope > open`.
|
||||
///
|
||||
/// # Examples
|
||||
///
|
||||
|
||||
@@ -248,7 +248,7 @@ impl Scope {
|
||||
|
||||
/// Open a path in the default (or specified) browser.
|
||||
///
|
||||
/// The path is validated against the `tauri > allowlist > shell > open` validation regex, which
|
||||
/// The path is validated against the `plugins > shell > open` validation regex, which
|
||||
/// defaults to `^((mailto:\w+)|(tel:\w+)|(https?://\w+)).+`.
|
||||
pub fn open(&self, path: &str, with: Option<Program>) -> Result<(), Error> {
|
||||
// ensure we pass validation if the configuration has one
|
||||
|
||||
Reference in New Issue
Block a user