Skip to main content

Getting Started

This guide walks you through creating, debugging, packaging, and installing your first PaTab widget in a few minutes.

Prerequisites​

  • Node.js ^22.18.0 || >=24.12.0
  • Any package manager (npm / pnpm / yarn / bun)

1. Create a Project with the Scaffolder​

Use your preferred package manager to invoke the scaffolder — all four commands invoke the same one:

npm create patab-widget@latest my-widget

You can also omit the project name, for example by running pnpm create patab-widget. The interactive terminal then asks for the project name and template:

项目名称：my-widget
选择模板：1) vue-ts  2) vanilla-ts [1]：
  • vue-ts (default, press Enter to select): Vue 3 SFC + @vitejs/plugin-vue
  • vanilla-ts: vanilla TypeScript, no framework

You can also skip the prompt directly with --template (in non-interactive environments such as CI this option is required):

npm create patab-widget@latest my-widget --template vanilla-ts

The scaffolder only generates files and does not install dependencies automatically. It refuses to overwrite an existing target directory.

2. Install Dependencies and Start the Local Simulator​

cd my-widget
npm install
npm run dev

dev actually runs patab-widget dev, which starts the local simulator and prints:

模拟器已启动：http://127.0.0.1:5174/__patab_widget_simulator__

Open that address in a browser to see the simulator: on the right is the widget surface running in a sandbox="allow-scripts" iframe, and the left control panel lets you switch surfaces, sizes, variants, theme, language, and reduced-motion preference, as well as mock confirm dialogs, network responses, and toast logs. The simulator is based on the Vite dev server, so source changes hot-reload instantly.

Simulator ≠ Direct Host Connection

The PaTab host has no debug URL entry point — during development you do not paste a local address into PaTab. The simulator is a standalone local debugging environment; to verify real integration, package the widget and re-import it into PaTab as described below.

3. Validate and Build​

npm run check   # Validate Manifest + build all surfaces + integrity/quota checks (no ZIP written)
npm run build   # Only verify that each surface builds into self-contained HTML (no artifacts written to disk)

4. Package into a Distributable File​

npm run pack

pack first force-runs the project's type-check (tsc --noEmit), then builds and inlines all surfaces, generates the integrity manifest, runs full package validation, and finally writes a deterministic ZIP:

组件包已生成：<id>-<version>.patab.zip（未签名）

The artifact is located at dist/<id>-<version>.patab.zip by default. Two pack runs with identical input produce byte-identical ZIPs.

For signed distribution, first generate an Ed25519 key pair with patab-widget keygen, paste the printed public key into publisher.publicKey of patab.manifest.json, then run patab-widget pack --sign <私钥路径>. See the CLI Reference for details.

5. Install in PaTab​

Open a PaTab new-tab page and select the generated .patab.zip file through the widget import entry. PaTab statically reviews the package (Manifest, assets, integrity, signature — widget code is never executed during this process) and displays the widget's name, version, developer, signature status, permissions, and network origin declarations. After you confirm the required permissions and network origins, the widget is installed and can then be added to the grid as a tile.

Next Steps​