Skip to content
ShiftPane
Documentation

Quickstart

From npm create to a widget on your phone, with the SDK and the CLI.

From nothing to a widget on your phone, with live data, in a few minutes. You need Node 22 or later and the ShiftPane desktop app.

Create a widget

Terminal
npm create shiftpane-widget@latest

It asks for a folder, the widget's name, your GitHub login (the widget's author), and a template:

TemplateWhat it gives you
pcA view bound to the PC's CPU. No collector, no code.
webA collector that fetches from one host (GitHub, to start), and a view for its JSON.

Pass them as flags to skip the questions. npx create-shiftpane-widget my-widget --template web --author your-login works in every shell; with npm create, the flags need a -- before them, which Windows PowerShell drops.

Run the collector

Terminal
npx shiftpane-widget dev

It checks the folder, runs the collector on a sample PC, and prints what it returned. It runs again every time you save. Give config values with --config key=value; secrets a widget declares, such as GITHUB_TOKEN, come from environment variables of the same name.

See it on your phone

  1. Turn on Developer mode

    In the desktop app, open Settings and turn on Developer mode.

  2. Load the folder

    Open Widgets → Installed and press Choose a folder. The app shows what the widget can do, then installs it. Add it to your board from Phone layout.

  3. Edit

    Change view.json or collector.js and save. The app loads the folder again and your phone redraws. A change that asks for a new permission isn't applied on its own: press Load again in the widget's settings, and the app asks you first.

Check and pack

Terminal
npx shiftpane-widget validate   # every check the gallery runs that can run on your PC
npx shiftpane-widget pack       # <id>-<version>.zip, the file the gallery takes

The zip is deterministic: the same folder always packs to the same bytes and the same SHA-256.

Share it

Terminal
npx shiftpane-widget login      # once: a code to type on GitHub
npx shiftpane-widget publish    # checks, packs and uploads this folder

Or, with Developer mode on, open the widget's settings in Widgets → Installed and use Share to the marketplace, or upload the zip on the Publish page. See Publishing for what happens next.