Development¶
Requirements¶
- Node.js 22 or later, npm.
- Docker (development server, plugin validator).
- just, uv (documentation).
- On Windows,
@grafana/create-pluginitself does not run (seeupstream-bugs.md); the generated project builds and tests on Windows.
Commands¶
| Command | Does |
|---|---|
just install |
npm ci |
just check |
type check, lint, unit and component tests |
just build |
production bundle in dist/ |
just server |
Grafana OSS 13.2.2 with the plugin and the provisioned dashboards; GRAFANA_PORT=3001 just server to use another port |
just e2e |
Playwright tests against the running server (GRAFANA_PORT as above) |
just docs |
documentation in site/, strict, with llms.txt and llms-full.txt; published to https://anywidgetinstruments.github.io/afm-host-panel/ by the Documentation workflow on each push to main |
just validate |
Grafana plugin validator (Docker) on a packaged dist/ |
If your npm configuration sets os to another platform, platform packages
such as @swc/core-win32-x64-msvc are skipped; install with
npm ci --os=<your platform>.
Layout¶
See AGENTS.md. The AFM host core is in src/afm/ and has no React
dependency; src/components/ holds the panel and its option editors.
Tests¶
src/**/*.test.ts(x): Jest (jsdom), including Testing Library tests of the panel with a spy widget.tests/*.spec.ts: Playwright with@grafana/plugin-e2e, against the provisioned dashboardsdemo.jsonandremote.json. Start the server withjust serverfirst. The CI runs them on Grafana OSS (grafana/grafana), for each version chosen bygrafana/plugin-actions/e2e-version(from the minimum version ofplugin.jsonto nightly).
Write the test first (TDD). Each requirement of the specification is named in the test titles.
Screenshots¶
With the development server running (just server):
node scripts/screenshots.mjs # or: node scripts/screenshots.mjs http://localhost:3001
The script writes the images, in the dark and light themes, to docs/img/
(README and documentation site, which shows the one matching its theme) and
those listed in the screenshots of plugin.json (plugin catalog) to
src/img/screenshots/. Take them again when a provisioned dashboard or the
panel editor changes.
Updating the vendored libraries¶
cd ../anywidget-instruments-industrial && npm ci && npm run build && cd -
node scripts/vendor-instruments.mjs ../anywidget-instruments-industrial
cd ../anywidget-instruments-automotive && npm ci && npm run build && cd -
node scripts/vendor-automotive.mjs ../anywidget-instruments-automotive
cd ../anywidget-instruments-aeronautics && npm ci && npm run build && cd -
node scripts/vendor-aeronautics.mjs ../anywidget-instruments-aeronautics
Each script copies the built module and CSS unmodified, with the upstream
license and commit (src/widgets/anywidget-instruments-industrial/SOURCE.json and
src/widgets/anywidget-instruments-automotive/SOURCE.json). Commit the
result with the commit hashes in the message.
Releases¶
The project follows Semantic Versioning. Development phases are 0.0.x
milestones (see Roadmap). Record every notable change in
CHANGELOG.md.