plugin.toml

The manifest names your plugin, picks its tile size and says how to start it. Nook reads it once at start-up, or on every save in dev mode.

toml

id          = "weather"
name        = "Weather"
icon        = "cloud-sun"
size        = "wide"
run         = ["python", "main.py"]
mode        = "live"
hotkey      = "ctrl+alt+KeyW"
description = "Current weather for your city."
version     = "1.0.0"

Keys

Key	Default	What it does
`id`	required	Unique, 1 to 48 characters of `a-z 0-9 - _`. Nook stores it as `plugin:<id>` in its config.
`name`	required	Shown in the page header and the tile editor.
`run`	required	Program and arguments, e.g. `["node", "main.js"]`. Runs in the plugin folder. A path like `"bin/tool.exe"` is resolved inside the folder; other names come from `PATH`.
`icon`	`"puzzle-piece"`	A Phosphor icon name, shown in the tile editor and on the default tile.
`size`	`"small"`	`small` (1x1), `wide` (2x1) or `large` (2x2). Users can resize it anyway.
`mode`	`"live"`	`live` keeps one process running; `poll` re-runs it. See How it works.
`interval`	`60`	Seconds between runs in poll mode (at least 1).
`hotkey`	none	A global shortcut, e.g. `"ctrl+alt+KeyY"`. Pressing it sends you `hotkey`.
`accepts_files`	`false`	While your page is open, files dropped on the notch are sent to you as `files`.
`page_size`	panel size	`[width, height]` in points. The panel grows to this while your page is open.
`description`, `author`, `version`	empty	Information only. The version is written to Nook's log and the marketplace.

Space to draw in

Nook tells you the exact space in a layout message, since the user may resize your tile. The usual content sizes are:

Target	Width × height (points)
small tile	44 × 44
wide tile	104 × 36
large tile	104 × 104
page	536 × 168

Environment

Variable	Value
`NOOK_PLUGIN_ID`	Your id.
`NOOK_PLUGIN_DIR`	Your folder (also the working directory).
`NOOK_DATA_DIR`	`%APPDATA%\Nook\plugin-data\<id>`. Save settings and data here, not in the plugin folder, so updates don't overwrite them.
`NOOK_THEME`, `NOOK_ACCENT`	`dark` or `light`, and the accent as `#RRGGBB`.
`NOOK_MODE`, `NOOK_PROTOCOL`, `NOOK_VERSION`	`live` or `poll`, `1`, and Nook's version.
`NOOK_EVENT`	Poll mode only: the event that caused this run, as JSON.

Python and Node also get PYTHONUNBUFFERED=1 and PYTHONIOENCODING=utf-8, so prints arrive right away.