Develop and debug

Keep your plugin where you work on it, let Nook reload it on every save, and read the log when something looks wrong.

Dev mode

Turn on Plugin dev mode in Nook's Settings (the card under the two columns). While it is on:

• saving any file in a plugin's folder restarts that plugin and re-reads its plugin.toml (name, icon, size, page size);
• a new plugin folder is loaded within a second, and a deleted one is unloaded. Changing id loads the plugin under its new id;
• nothing needs a restart of Nook.

Turn it off when you're done: it checks the plugin folders once a second while it's on.

Build Nook from source

You need Nook built from source to run it against your own plugin folder. It takes about five minutes on a fresh machine, most of it downloading the compiler.

Install the MSVC compiler and a Windows SDK from Visual Studio 2022 Build Tools:

winget install --id Microsoft.VisualStudio.2022.BuildTools -e --override "--quiet --wait --add Microsoft.VisualStudio.Workload.VCTools --includeRecommended"

Install Rust. rustup installs the pinned MSVC toolchain on the first build:

winget install --id Rustlang.Rustup -e

Then build and run from the Nook folder. Press Ctrl + Alt + N to pin the panel open.

cargo run --release

Run Nook against your folder

Point Nook at the folder that contains your plugin, then run it from a terminal:

$env:NOOK_PLUGIN_PATH = "C:\code\my-plugins"     # ; separates folders
$env:NOOK_PLUGIN_DEV  = "1"                       # dev mode, without touching Settings
cargo run --release -- --pinned --page=plugin:hello

NOOK_PLUGIN_DEV=1 (or --plugin-dev) turns dev mode on for that run, whatever Settings say. --page=plugin:<id> opens on your page.

Plugins are searched for in this order: %APPDATA%\Nook\plugins, plugins\ next to nook.exe, then each folder in NOOK_PLUGIN_PATH. If two plugins have the same id, the first one found wins.

Test without Nook

Your plugin is just a program, so send it messages yourself:

'{"type":"event","id":"wave","kind":"click"}' | python main.py

Read the log

%APPDATA%\Nook\nook.log has every plugin's stderr, its log messages and each line Nook couldn't parse, with the reason (for example bad "button" view: missing field id). Set NOOK_LOG=debug for more.

When it crashes

Nook restarts the plugin up to three times a minute. After that the tile shows Stopped · click to restart, and hovering over it shows the error and the last lines of stderr. The page shows the same details with a Restart button.