docs(api): document allowlist for each module (#1853)

tooling/api/README.md

@@ -1,4 +1,4 @@
-# @tauri-apps/cli
+# @tauri-apps/api
  <img align="right" src="https://github.com/tauri-apps/tauri/raw/dev/app-icon.png" height="128" width="128">
 
 [![status](https://img.shields.io/badge/Status-Beta-green.svg)](https://github.com/tauri-apps/tauri)
@@ -12,9 +12,9 @@
 [![https://good-labs.github.io/greater-good-affirmation/assets/images/badge.svg](https://good-labs.github.io/greater-good-affirmation/assets/images/badge.svg)](https://good-labs.github.io/greater-good-affirmation)
 [![support](https://img.shields.io/badge/sponsor-Opencollective-blue.svg)](https://opencollective.com/tauri)
 
-| Component | Version                                     |
-| --------- | ------------------------------------------- |
-| @tauri-apps/api   | ![](https://img.shields.io/npm/v/@tauri-apps/api.svg) |
+| Component       | Version                                               |
+| --------------- | ----------------------------------------------------- |
+| @tauri-apps/api | ![](https://img.shields.io/npm/v/@tauri-apps/api.svg) |
 
 ## About Tauri
 Tauri is a polyglot and generic system that is very composable and allows engineers to make a wide variety of applications. It is used for building applications for Desktop Computers using a combination of Rust tools and HTML rendered in a Webview. Apps built with Tauri can ship with any number of pieces of an optional JS API / Rust API so that webviews can control the system via message passing. In fact, developers can extend the default API with their own functionality and bridge the Webview and Rust-based backend easily.

tooling/api/src/app.ts

@@ -4,6 +4,7 @@
 
 /**
  * Get application metadata.
+ *
  * This package is also accessible with `window.__TAURI__.app` when `tauri.conf.json > build > withGlobalTauri` is set to true.
  * @packageDocumentation
  */

tooling/api/src/cli.ts

@@ -4,6 +4,7 @@
 
 /**
  * Parse arguments from your Command Line Interface.
+ *
  * This package is also accessible with `window.__TAURI__.cli` when `tauri.conf.json > build > withGlobalTauri` is set to true.
  * @packageDocumentation
  */

tooling/api/src/dialog.ts

@@ -4,7 +4,24 @@
 
 /**
  * Native system dialogs for opening and saving files.
+ *
  * This package is also accessible with `window.__TAURI__.dialog` when `tauri.conf.json > build > withGlobalTauri` is set to true.
+ *
+ * The APIs must be allowlisted on `tauri.conf.json`:
+ * ```json
+ * {
+ *   "tauri": {
+ *     "allowlist": {
+ *       "dialog": {
+ *         "all": true, // enable all dialog APIs
+ *         "open": true, // enable file open API
+ *         "save": true // enable file save API
+ *       }
+ *     }
+ *   }
+ * }
+ * ```
+ * It is recommended to allowlist only the APIs you use for optimal bundle size and security.
  * @packageDocumentation
  */
 

tooling/api/src/event.ts

@@ -4,6 +4,7 @@
 
 /**
  * The event system allows you to emit events to the backend and listen to events from it.
+ *
  * This package is also accessible with `window.__TAURI__.event` when `tauri.conf.json > build > withGlobalTauri` is set to true.
  * @packageDocumentation
  */

tooling/api/src/fs.ts

@@ -4,7 +4,32 @@
 
 /**
  * Access the file system.
+ *
  * This package is also accessible with `window.__TAURI__.fs` when `tauri.conf.json > build > withGlobalTauri` is set to true.
+ *
+ * The APIs must be allowlisted on `tauri.conf.json`:
+ * ```json
+ * {
+ *   "tauri": {
+ *     "allowlist": {
+ *       "fs": {
+ *         "all": true, // enable all FS APIs
+ *         "readTextFile": true,
+ *         "readBinaryFile": true,
+ *         "writeFile": true,
+ *         "writeBinaryFile": true,
+ *         "readDir": true,
+ *         "copyFile": true,
+ *         "createDir": true,
+ *         "removeDir": true,
+ *         "removeFile": true,
+ *         "renameFile": true
+ *       }
+ *     }
+ *   }
+ * }
+ * ```
+ * It is recommended to allowlist only the APIs you use for optimal bundle size and security.
  * @packageDocumentation
  */
 

tooling/api/src/globalShortcut.ts

@@ -4,7 +4,22 @@
 
 /**
  * Register global shortcuts.
+ *
  * This package is also accessible with `window.__TAURI__.globalShortcut` when `tauri.conf.json > build > withGlobalTauri` is set to true.
+ *
+ * The APIs must be allowlisted on `tauri.conf.json`:
+ * ```json
+ * {
+ *   "tauri": {
+ *     "allowlist": {
+ *       "globalShortcut": {
+ *         "all": true // enable all global shortcut APIs
+ *       }
+ *     }
+ *   }
+ * }
+ * ```
+ * It is recommended to allowlist only the APIs you use for optimal bundle size and security.
  * @packageDocumentation
  */
 

tooling/api/src/http.ts

@@ -4,7 +4,23 @@
 
 /**
  * Access the HTTP client written in Rust.
+ *
  * This package is also accessible with `window.__TAURI__.http` when `tauri.conf.json > build > withGlobalTauri` is set to true.
+ *
+ * The APIs must be allowlisted on `tauri.conf.json`:
+ * ```json
+ * {
+ *   "tauri": {
+ *     "allowlist": {
+ *       "http": {
+ *         "all": true, // enable all http APIs
+ *         "request": true // enable HTTP request API
+ *       }
+ *     }
+ *   }
+ * }
+ * ```
+ * It is recommended to allowlist only the APIs you use for optimal bundle size and security.
  * @packageDocumentation
  */
 

tooling/api/src/index.ts

@@ -4,6 +4,7 @@
 
 /**
  * The Tauri API allows you to interface with the backend layer.
+ *
  * This module exposes all other modules as an object where the key is the module name, and the value is the module exports.
  * @example
  * ```typescript

tooling/api/src/notification.ts

@@ -4,7 +4,22 @@
 
 /**
  * Send notifications to your user. Can also be used with the Notification Web API.
+ *
  * This package is also accessible with `window.__TAURI__.notification` when `tauri.conf.json > build > withGlobalTauri` is set to true.
+ *
+ * The APIs must be allowlisted on `tauri.conf.json`:
+ * ```json
+ * {
+ *   "tauri": {
+ *     "allowlist": {
+ *       "notification": {
+ *         "all": true // enable all notification APIs
+ *       }
+ *     }
+ *   }
+ * }
+ * ```
+ * It is recommended to allowlist only the APIs you use for optimal bundle size and security.
  * @packageDocumentation
  */
 

tooling/api/src/path.ts

@@ -7,7 +7,23 @@ import { BaseDirectory } from './fs'
 
 /**
  * Read common system paths such as home, config and cache directories.
+ *
  * This package is also accessible with `window.__TAURI__.path` when `tauri.conf.json > build > withGlobalTauri` is set to true.
+ *
+ * The APIs must be allowlisted on `tauri.conf.json`:
+ * ```json
+ * {
+ *   "tauri": {
+ *     "allowlist": {
+ *       "fs": {
+ *         "all": true, // enable all FS APIs
+ *         "path": true // enable path APIs
+ *       }
+ *     }
+ *   }
+ * }
+ * ```
+ * It is recommended to allowlist only the APIs you use for optimal bundle size and security.
  * @packageDocumentation
  */
 

tooling/api/src/process.ts

@@ -6,6 +6,7 @@ import { invokeTauriCommand } from './helpers/tauri'
 
 /**
  * Perform operations on the current process.
+ *
  * This package is also accessible with `window.__TAURI__.process` when `tauri.conf.json > build > withGlobalTauri` is set to true.
  * @packageDocumentation
  */

tooling/api/src/shell.ts

@@ -8,7 +8,24 @@ import { transformCallback } from './tauri'
 /**
  * Access the system shell.
  * Allows you to spawn child processes and manage files and URLs using their default application.
+ *
  * This package is also accessible with `window.__TAURI__.shell` when `tauri.conf.json > build > withGlobalTauri` is set to true.
+ *
+ * The APIs must be allowlisted on `tauri.conf.json`:
+ * ```json
+ * {
+ *   "tauri": {
+ *     "allowlist": {
+ *       "shell": {
+ *         "all": true, // enable all shell APIs
+ *         "execute": true, // enable process spawn APIs
+ *         "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.
  * @packageDocumentation
  */
 

tooling/api/src/tauri.ts

@@ -4,6 +4,7 @@
 
 /**
  * Invoke your custom commands.
+ *
  * This package is also accessible with `window.__TAURI__.tauri` when `tauri.conf.json > build > withGlobalTauri` is set to true.
  * @packageDocumentation
  */

tooling/api/src/updater.ts

@@ -4,6 +4,7 @@
 
 /**
  * Customize the auto updater flow.
+ *
  * This package is also accessible with `window.__TAURI__.updater` when `tauri.conf.json > build > withGlobalTauri` is set to true.
  * @packageDocumentation
  */

tooling/api/src/window.ts

@@ -4,7 +4,23 @@
 
 /**
  * Provides APIs to create windows, communicate with other windows and manipulate the current window.
+ *
  * This package is also accessible with `window.__TAURI__.window` when `tauri.conf.json > build > withGlobalTauri` is set to true.
+ *
+ * The APIs must be allowlisted on `tauri.conf.json`:
+ * ```json
+ * {
+ *   "tauri": {
+ *     "allowlist": {
+ *       "window": {
+ *         "all": true, // enable all window APIs
+ *         "create": true // enable window creation
+ *       }
+ *     }
+ *   }
+ * }
+ * ```
+ * It is recommended to allowlist only the APIs you use for optimal bundle size and security.
  * @packageDocumentation
  */