If you’ve ever wanted a Setup page that looks and behaves like a real Checkmk
Quick Setup — using the actual CmkButton, CmkWizard, FormEdit, … — rather
than an iframe or a hand-reimplemented lookalike, here’s a fork-and-go template
for exactly that.
GitHub - otAAAh/checkmk-vue-plugin-template: Template: build Checkmk GUI plugins with a native Vue frontend (compiled against the site's own cmk-frontend-vue) · GitHub — hit the green
“Use this template” button, rename a few identifiers, done.
The problem
Checkmk’s Vue components (cmk-frontend-vue) are internal and unversioned. So the
obvious options are both bad: reimplement the components yourself (drifts
immediately, never quite matches the theme), or vendor a snapshot (rots the moment
the site updates).
The approach: a build-time bridge, not vendoring
Your Vue code imports the components straight from a Checkmk source checkout:
import CmkButton from '@/components/CmkButton'
A small vite.config.ts mirrors cmk-frontend-vue’s own build aliases
(@ → its src, ~cmk-frontend → the theme dist), so the components compile
from source against the exact Checkmk version your site runs. Nothing is forked;
nothing to keep in sync.
The app is compiled to a custom element (defineCustomElement,
shadowRoot: false). A WatoMode page loads the site’s own theme CSS, loads your
bundle, and mounts it with html.vue_component(…) — the same mechanism Checkmk
uses for its own Vue apps — passing initial data from Python straight into the
app. Light-DOM + the site’s design tokens means it looks native in both light and
dark themes.
What’s in the box
- frontend/ — the Vue app + the Vite bridge; the hello-world App.vue renders
the real CmkButton/CmkHeading/CmkParagraph and reads data handed in from
Python. - gui/ — a WatoMode page that mounts the element, plus a Setup-menu entry.
- scripts/build_mkp.py — a stdlib-only MKP packager (no cmk import needed
to build), and dev-build-frontend.sh for a local build against your own
checkout + site. - .github/workflows/ — CI (ruff + mypy + build) and a version-matched
frontend build that compiles against a pinned Checkmk ref and lifts theme assets
from the matching check-mk-raw Docker image.
Quick start
scripts/dev-build-frontend.sh --setup # build against your Checkmk checkout + site
python3 scripts/build_mkp.py # → vue_plugin_example-0.1.0.mkp
mkp add vue_plugin_example-0.1.0.mkp && mkp enable vue_plugin_example 0.1.0
Setup ▸ Quick setups ▸ “Vue plugin example”
Then grow from the hello-world: add more @/components/Cmk*, render a
FormEdit against a FormSpec you serialize in Python, wire up AjaxPage endpoints
for save/validate.
Honest caveats
- Checkmk 2.5+ (the current component layout / radix-vue era).
- You’re building on internal, unversioned frontend + GUI APIs
(html.vue_component, the mode/main-module registries, the manifest layout).
They do drift between releases — which is why the build is version-matched and
the MKP declares a min_required. Pin your ref and re-test when you bump it. - Community/experimental, not an officially supported extension API. Think “here’s
how the sausage is made,” not a stability promise.
Feedback, issues and PRs very welcome. And I’m curious whether others have solved
the same problem differently.
