Toolkit

[中文]

ESP-Brookesia Toolkit is the npm CLI for initializing, building, packing, verifying, simulating, and deploying ESP-Brookesia app packages (.bpk).

The published package is esp-brookesia-toolkit.

Agent IDE integration (MCP) is documented separately: App Dev Plugin.

Environment Requirements

Node.js 20 or newer (>=20), with npm / npx on PATH. Matches the published Toolkit and plugin engines.node requirement.
After brookesia init --template js-bundle, run npm install in the app directory (the template pulls in @rspack/cli). js-gui, lua-gui, and wasm-gui have no extra npm dependencies.

Install the Toolkit

End users install the published CLI globally:

npm install -g esp-brookesia-toolkit
brookesia --help

The WASM simulator package @brookesia/simulator-wasm is installed as a CLI dependency and resolved from the global CLI, not from the app's node_modules. brookesia simulate needs the staged simulator artifacts inside that package. If they are missing, brookesia doctor reports it and simulate fails.

To bump the CLI later:

npm install -g esp-brookesia-toolkit@latest

After a global install, reopen the terminal if brookesia is missing from PATH.

Quick Start

Create and run a JavaScript GUI app:

brookesia init my-app --template js-gui
cd my-app
brookesia doctor
brookesia build
brookesia simulate

brookesia build creates a debug .bpk. For a signed release:

brookesia sign init
brookesia release
brookesia verify

Install the newest .bpk in dist/ onto hardware (requires Serial Command-Line Tool):

brookesia deploy
brookesia deploy --port /dev/ttyACM0

App Templates

brookesia init supports the following templates:

Toolkit App Templates
Template	Purpose	Notes
`js-gui`	JavaScript GUI app	Default template with GUI resources
`js-bundle`	Bundled JavaScript app	rspack-style bundler; run `npm install` in the app after init
`lua-gui`	Lua GUI app	No extra npm dependencies
`wasm-gui`	WebAssembly GUI app	Ship a prebuilt `.wasm` at `manifest.runtime.entry`. Native WASM compilation in the pipeline was removed; `wasm.sources` is rejected.

Example:

brookesia init test --template js-gui --dir my-app

Command Reference

brookesia --help
brookesia <command> --help

brookesia CLI Commands
Command	Description
`brookesia init <name>`	Create an app directory from a template; `--template` and `--dir` select the template and parent directory.
`brookesia doctor`	Check the app environment, WASM simulator artifacts, bundler, USB CLI, and connected device.
`brookesia build`	Development build; writes a debug `.bpk` under `dist/`.
`brookesia release`	Release build; writes a signed release `.bpk`.
`brookesia sign init`	Generate signing keys under `sign/`.
`brookesia pack`	Pack a directory into a `.bpk` with `--source-dir` and `--output`; `--release` applies release signing.
`brookesia verify`	Verify a release `.bpk` signature; `--package` selects the file.
`brookesia simulate`	Start the WASM browser simulator (local HTTP server). There is no `--target` flag.
`brookesia deploy`	Install a `.bpk` onto a device via `brookesia-usb`; `--package` and `--port` are optional.

WASM Simulator

brookesia simulate launches only the WASM browser simulator:

brookesia simulate
brookesia simulate --package dist/my-app.debug.bpk
brookesia simulate --smoke --duration-ms 2000
brookesia simulate --gui-debug
brookesia simulate --resolution 1024x600
brookesia simulate --no-open --port 8787 --pid-file /tmp/brookesia-sim.pid
brookesia simulate --stop --pid-file /tmp/brookesia-sim.pid

simulate Options
Option	Description
`--package <bpk>`	Load this `.bpk` (default: newest file under `dist/`).
`--smoke`	Headless smoke: start non-running apps, then exit.
`--duration-ms <ms>`	Per-app duration for `--smoke`.
`--gui-debug`	JSON UI debug outlines.
`--resolution WxH`	Window size, for example `1024x600`.
`--no-open`	Do not open a browser.
`--port N`	HTTP port (default `8787`).
`--pid-file <path>`	Write the server PID; required with `--stop`.
`--stop`	Stop the server recorded by `--pid-file`.