Skip to content

Development

Requirements

  • Node.js 22 or later, npm.
  • Docker (development server, plugin validator).
  • just, uv (documentation).
  • On Windows, @grafana/create-plugin itself does not run (see upstream-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 dashboards demo.json and remote.json. Start the server with just server first. The CI runs them on Grafana OSS (grafana/grafana), for each version chosen by grafana/plugin-actions/e2e-version (from the minimum version of plugin.json to 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.