# Writing a wayBetter for X plugin Plugins are BetterDiscord-style: one `*.plugin.js` file, a class with `start()` and `stop()`. Install one from **wayBetter → Store**, drop the file on the wayBetter window, open a `waybetter://install` link, or copy it into **wayBetter → Plugins → Open folder** and press **Rescan**. Everything except copying by hand shows the install screen first (see [Installing](#installing-links-files-and-the-store)). It starts and stops live, on every X page. To start from a working example, open **wayBetter → Make** (example plugins, the UI kit gallery and the live theme API), or scaffold a file or a TypeScript project with `npm create waybetter plugin -- --name "My Plugin"` (add `--ts`). ## The smallest plugin ```js /** * @name Hide Trends * @description Hides the right-column trends box. * @version 1.0.0 * @author you * @permissions network:none */ module.exports = class HideTrends { start() { wayBetter.api.injectCSS('hide-trends', '[data-testid="sidebarColumn"] section { display: none }'); } stop() { wayBetter.api.clearCSS('hide-trends'); } }; ``` The header comment is required: `@name`, `@description`, `@version`, `@author`, and it should declare `@permissions` (next section). ## Permissions A header declares what the plugin uses from the gated part of the API: | Permission | Unlocks | Shown as | | --- | --- | --- | | `storage` | `api.storage(ns)` | Storage | | `ui` | `api.ui`, `api.toast`, `scope.ui` | Dialogs | | `clipboard` | `api.copyText` | Clipboard | | `account` | `api.account()` (the signed-in handle, name, avatar) | Your account | | `users` | `api.users` (what X's own responses said about accounts) | Account details | | `commands` | `api.commands`, `scope.commands` (command palette entries) | Commands | | `network` / `network:none` | nothing: a declaration (see below) | Internet / No network | Everything else needs no permission: `injectCSS`/`clearCSS`, `adoptCSS`, `waitFor`, `observe`, `onRouteChange`, `onKey`, `scope()` (css, adoptCSS, on, observe, add, defer, dispose, onThemeChange), `theme`, `tweet`, `isTypingTarget`. Separate names with commas or spaces (`@permissions storage, ui, network:none`); `none` alone means no gated API. While the plugin's module body, constructor, `start()` and `stop()` run, `window.wayBetter.api` is **that plugin's view**: a gated member it did not declare throws a `PluginPermissionError` such as `my.plugin.js: api.copyText needs the "clipboard" permission. Add it to the plugin's header: @permissions clipboard`. Keep the reference you read there (`const api = window.wayBetter.api` in `start()`, or a scope) and use it in your callbacks. The install screen, the Store and the Plugins list show the permissions; a header with an unknown permission is refused at install. A plugin **without** a `@permissions` line is *legacy*: it gets the whole API as before and the app labels it "Legacy · full page access". New plugins should always declare. **What permissions are, honestly.** A plugin is JavaScript in the X page. It can read and change the page, call `fetch`, reach `window.wayBetter` directly, and nothing running in the page can stop code that tries to get around a check. Permissions are two things: a declaration you (and store reviewers) read before installing, and a guard rail that makes honest code fail loudly when it uses something it did not declare. They are not a sandbox. `network:none` is a promise: at install time the app scans the code and refuses a file that declares `network:none` but calls `fetch`, `XMLHttpRequest`, `WebSocket`, `EventSource` or `sendBeacon`; minified or obfuscated code can hide calls from a scan, so read what you install. ## Clean up with a scope A scope collects everything a plugin adds and undoes it in one call, so `stop()` leaves X exactly as it was: ```js module.exports = class Example { start() { const api = wayBetter.api; this.scope = api.scope(); this.scope.css('example', '.my-note { opacity: .6 }'); this.scope.observe('article[data-testid="tweet"]', article => { /* decorate each post */ }); this.scope.onKey((event, tweet) => { if (event.key === 'c' && tweet) api.copyText(api.tweet(tweet).url); }); } stop() { this.scope.dispose(); } }; ``` ## API: `window.wayBetter.api` Everything is local to the page: no network requests, no account actions. (`window.BetterTwttr` is the same object, kept for older plugins.) | Helper | What it does | | --- | --- | | `injectCSS(id, css)` / `clearCSS(id)` | Adds, replaces or removes a `