wayBetter, the framework, and wayBetter for X, the first app built on it

wayBetter

Make the apps you use way better. A framework for light desktop apps that wrap one website and extend it in place, the way BetterDiscord extends Discord.
GPL-3.0-or-later · npm create waybetter

waybetter.fyi · npm · Architecture · Store · String packs · wayBetter for X

npm license: GPL-3.0-or-later runtime dependencies: 0 Tauri 2 platforms: macOS, Windows, Linux

You bring a site and a small adapter that says what the site is. wayBetter gives you the rest: a Tauri 2 window with tabs, split panes and every account signed in side by side; a page runtime with a plugin API, a theme engine and string packs; a signed Store with a safe install screen; backups, encrypted sync and signed updates; and the tooling to scaffold, sign, scan and release it. | What you get | | | --- | --- | | **A window around the site** | Tabs in the titlebar, split panes, an address bar per tab, command palette, decks of columns, workspaces. One WebView profile per account, so all of them stay signed in. | | **Plugins** | `*.plugin.js` files with a declared `@permissions` line, a themed UI kit (toast, dialog, prompt), commands in the palette, live reload in developer mode. | | **Themes** | One JSON document: colours with contrast enforced, fonts per role (Google Fonts downloaded once, after asking), shapes, layout, decoration, icon packs, per-pane and per-account themes, a Theme Builder with a doctor report. | | **String packs** | Data that re-words the site's own interface: a language it does not offer, a fix, your own wording. Never code. | | **A signed Store** | One Ed25519-signed catalog for every wayBetter app, `waybetter://install` links, drag-and-drop and Open With, all through one install screen that shows the source, SHA-256, permissions and code first. | | **Release tooling** | `waybetter store`, `release`, `build-env`, `i18n` and `strings`: sign the catalog and build binaries free of the builder's paths. | ## How it fits together A wayBetter app is one Tauri 2 window with several webviews. The framework has one piece for each layer and does not need to know which site you wrap. | Layer | Where | What it does | | --- | --- | --- | | Native host | `crates/waybetter-host` (Rust) | Builds the window, the trusted `shell` webview and one child webview per tab, keeps profiles (each with its own WebView data folder), the plugin store, settings, backups, encrypted sync, updates, fonts, the store install rules, and decides which webview may call which command. | | Page runtime | `packages/runtime` (TypeScript, no dependencies) | Injected into tabs that are on the site's exact origin: one DOM hub and one fetch/XHR hub, the plugin API and its themed UI kit, the theme engine, split-view navigation, link routing, account reporting, deck columns, string packs. | | Shell | `packages/shell` (TypeScript and React) | The local UI around the tabs: `createShell(site)` gives tabs in the titlebar, split panes, address bar, command palette, account switcher, decks and workspaces; `createPanel(site)` gives the app's own settings tab (appearance, theme builder, plugins, store, backup, developer mode). | Details of every module are in [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md). ## Quick start ```sh npm create waybetter app kickapp -- --site kick.com --name "wayBetter for Kick" --yes ``` ![npm create waybetter app: Created a wayBetter app in kickapp (32 files), then the next steps: cd kickapp, add the framework as a git submodule, npm install, npm run build, npm run tauri dev](assets/readme/term/create-app.webp) The same tool starts a plugin or a theme: ```sh npm create waybetter plugin -- --name "Hide Trends" # add --ts for TypeScript npm create waybetter theme -- --name "Midnight Mint" --accent "#3ddc97" ``` ![npm create waybetter plugin: a Hide Trends plugin file and how to install it](assets/readme/term/create-plugin.webp) The app scaffold adds the framework as a git submodule at `waybetter/` by default (`--host-source path` and `--host-source git` are the alternatives). After `npm run tauri dev`, replace the placeholder selectors in `src/site.ts` and `src-tauri/src/site.rs`. All flags: `npm create waybetter -- --help`, and [packages/create-waybetter](packages/create-waybetter/README.md). Inside an app, plugins and themes are plain files, the docs and examples are built in, and developer mode reloads them as you save: ## Packages | Package | Where | What it is | | --- | --- | --- | | [`waybetter`](https://www.npmjs.com/package/waybetter) | `packages/waybetter` | The npm package: the built runtime and shell (plain ESM with `.d.ts`), JSON Schemas for themes, icon packs, catalogs and i18n, the locales, and the `waybetter` command (`dev`, `store`, `release`, `i18n`, `strings`, `build-env`) | | `create-waybetter` | `packages/create-waybetter` | `npm create waybetter`: scaffolds a plugin (JS or TypeScript), a theme or a whole app. No dependencies | | `@waybetter/runtime` | `packages/runtime` | The page runtime (published inside `waybetter`) | | `@waybetter/shell` | `packages/shell` | Shell models, frame, panel and Store screens (published inside `waybetter`) | | `waybetter-host` | `crates/waybetter-host` | The Rust host crate (features `tauri`, `net`, `app`), used from source as a git submodule or a path dependency | ## Built with wayBetter
wayBetter for X: a theme per pane, two accounts in one window wayBetter for X: fourteen themes, each a full redesign
wayBetter for X (x.com; macOS, Windows, Linux). Tabs, split panes, every account side by side, a deck, 14 themes, eight area plugins, string packs, drafts, and fixes for X's own bugs. waybetter.fyi/x
Built something on wayBetter? Add it here with a pull request. ## A minimal adapter An adapter is three small things. This is what `npm create waybetter app` writes for `kick.com` (selectors are placeholders you replace after looking at the real site). **1. Native: which webviews are site tabs, and what an account looks like** (`src-tauri/src/site.rs`) ```rust use waybetter_host::site::{AccountRules, SiteSpec}; pub fn valid_handle(handle: &str) -> bool { (3..=25).contains(&handle.len()) && handle.bytes().all(|b| b.is_ascii_alphanumeric() || b == b'_') } pub static SITE: SiteSpec = SiteSpec { product: "wayBetter for Kick", hosts: &["kick.com"], // exact https origin(s): the only definition of a site tab runtime_global: "WayBetterForKick", // window. of the page runtime accounts: AccountRules { valid_handle, avatar_prefixes: &["https://files.kick.com/"], max_name_chars: 50, max_avatar_len: 512, }, }; ``` **2. Page: what the runtime needs to know about the markup** (`src/site.ts`, shortened) ```ts import type { SiteAdapter } from 'waybetter/runtime/site'; export const SITE: SiteAdapter = { product: 'wayBetter for Kick', hosts: ['kick.com'], runtimeGlobal: 'WayBetterForKick', heavyPath: null, apiMarks: ['/api/'], // request URLs the net hub may inspect xhrMarks: [], plugins: { name: 'WayBetterForKick', product: 'wayBetter for Kick', storagePrefix: 'wb-kick-plugin:', styleDataKey: 'wbKickPlugin', toastId: 'wb-kick-ui', toastBackground: '#53fc18', itemSelector: '[data-chat-entry]', chordKeys: [] }, account: { read: readAccount, signedOut: root => !!root.querySelector('button[data-testid="login"]') }, links: { configKey: 'site', clickedUrl }, }; ``` **3. Capabilities: who may call what** (`src-tauri/capabilities/*.json`, keyed by webview label). The scaffold writes `shell`, `tab-chrome` and `site-tab`; the last one is granted only on the site's own URLs: ```json { "identifier": "site-tab", "webviews": ["tab-*"], "local": false, "remote": { "urls": ["https://kick.com/*"] }, "permissions": ["allow-site-ready", "allow-open-panel"] } ``` The app itself is `waybetter_host::app` configured with an `AppConfig` and a `SiteHooks` implementation (what only your site knows: page scripts, legacy domains, link routing). Anything else the app needs is an ordinary `#[tauri::command]` in your crate. ## The dev loop In a scaffolded app, `npm run dev` runs `waybetter dev --watch "node scripts/build.mjs --watch"`: it starts your watchers, waits for their first build and runs `tauri dev`. In debug builds the page runtime file is read from disk and watched; when it changes, every tab webview is rebuilt on its current URL (about a second from save to visible, the route is kept, the scroll position is not). The shell reloads through the frontend dev server. Rust, `tauri.conf.json`, capabilities and bundled plugin sources need a restart. `npm run dev:stable` adds `--no-watch` so a Rust file saved elsewhere does not restart the app. Release builds contain none of this. There is also a developer mode in the panel (Settings, Developer) that reloads installed plugins, custom CSS and one theme file in every tab as you save. ## Security model The site's page is not trusted, and neither is a plugin. The rules: - Capabilities are keyed by webview label and each command re-checks its caller in Rust: the capability file is not the boundary. A `tab-*` webview may only report about itself (`tab_report`, `tab_shortcut`, `tab_link_drag`); on the site's exact origin it also gets the app's short, reviewed list of site commands and `open_panel`. Everything else (tab layout, settings, plugins, backup, install) is callable from the local `shell` webview only. - `SiteSpec::is_origin` is the single definition of "a site tab": exact https origin, no credentials in the URL. - The account a tab reports is recorded only for that tab's own profile, only while it is on the site, validated by your `AccountRules`, and a settings save can never change it. - Installs (themes, plugins) come from a dropped file, a `waybetter://install` link or the signed store, and are written only after the owner confirms in the shell. The store catalog is verified with Ed25519; downloads use an allow-list, no redirects, no cookies and size caps. Plugins may declare `@permissions`; the runtime gives each an API view that throws on undeclared members. That is a guard rail, not a sandbox. A plugin without the line is labelled legacy and gets the full API. - Backups and sync snapshots never contain cookies, WebView profile folders, tokens or signing keys. Sync is encrypted with the owner's passphrase (Argon2id and XChaCha20-Poly1305). - `waybetter_host::testkit` lets your `tests/security.rs` read every capability file and assert that host commands stay shell-only or tab-only, that site commands are granted only on the site's URLs, and that each command's first statement checks its caller. The scaffold includes such a test. - `waybetter build-env` keeps a build free of the builder's paths. ## Optional command groups Beyond the commands every app gets, the host serves groups of shell-only commands that an app turns on in its `AppConfig` (or, for the state-free ones, simply grants in its shell capability). Each group is a list in `waybetter_host::commands`, each wrapper checks its caller first, and `waybetter_host::testkit` asserts both in your `tests/security.rs`. | Group | Turn on with | What it serves | What the app supplies | | --- | --- | --- | --- | | `STORE` | `AppConfig::with_store(&STORE)` | install links, dropped files, the signed Store, the install screen | its `StoreConfig` (app id, hosts, public keys) | | `MEDIA` | `with_media()` | gallery folders, previews, the opt-in clipboard history and its watcher | attaching an image to the site's composer, if it has one (`media_commands::gallery_file` and `clip_image` give it the checked bytes) | | `GFONTS` | `with_fonts()` | Google Fonts install, remove, preview (needs the `net` feature) | `SiteHooks::fonts_changed` (give the tabs their theme again) | | `UPDATE` | `with_updates(&UpdaterConfig)` | update status, check now, apply, the update loop and the hotfix channel | the channel, its key and the download page | | `SYNC` | `with_sync()` | encrypted folder sync | `SiteHooks::backup_sections` and `backup_section_names` | | `DEV` | `with_dev()` | developer mode: live reload of plugins, custom CSS and a theme file | `SiteHooks::dev_theme_apply` and `dev_theme_end` | | `WORKSPACES`, `BACKUP` | always served | saved layouts; settings backup (collect, export, open, apply) | for backup: `backup_drafts` and `backup_apply` (how each imported section is applied) | What is still the app's to write today: keyword alerts' commands around `waybetter_host::alerts`, the theme commands around `waybetter_host::theme` (wayBetter for X names them `x_*`), a popover webview and anything else that is specific to the site. They are on the list to move. ## Repository layout ``` crates/waybetter-host/ Rust host crate (features: tauri, net, app) packages/runtime/ page runtime (published inside `waybetter`) packages/shell/ shell models, shell frame, panel, store screens (published inside `waybetter`) packages/waybetter/ the npm package: built runtime and shell, JSON Schemas, locales, and the `waybetter` command (store, release, i18n, strings, build-env, dev) packages/create-waybetter/ `npm create waybetter` docs/ ARCHITECTURE.md, STORE.md, STRING-PACKS.md dev-tools/ harnesses for a running or built app (not published) ``` ## Tests ```sh bun install bun run typecheck # tsc over both packages, their tests and create-waybetter bun run test:ts # node --test: runtime and shell bun run test:rust # cargo test of the host crate (headless, feature net) bun run test:create # scaffolds each kind into temp folders and checks them against the real contracts ``` `test:create` also runs `cargo check` on a generated app (about a minute cold); `WAYBETTER_SKIP_CARGO_CHECK=1` skips that step. Requires Bun 1.4.2+, Node 24+ and Rust 1.88+. The README's terminal images are real output: `node tools/readme-term-shots.mjs` runs the commands and redraws `assets/readme/term/` (Google Chrome and cwebp). ## Docs - [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md): every module of the host, runtime and shell - [docs/STORE.md](docs/STORE.md): the signed catalog, install links and the install screen - [docs/STRING-PACKS.md](docs/STRING-PACKS.md): the string pack format and `waybetter strings check` - [packages/waybetter](packages/waybetter/README.md), [packages/create-waybetter](packages/create-waybetter/README.md), [packages/runtime](packages/runtime/README.md), [packages/shell](packages/shell/README.md) - A full app on the framework: [wayBetter for X](https://git.crt.fyi/CRT/waybetter-for-x), whose docs cover themes, plugins, area plugins and translating ## Contributing Issues and pull requests go to [git.crt.fyi/CRT/waybetter](https://git.crt.fyi/CRT/waybetter). Keep the split: generic mechanisms belong here, site-specific ones in the app. ## License GPL-3.0-or-later. Made by [@CRTkafa](https://x.com/CRTkafa).