Development

Development

Build locally

From the card repository, with Node.js and npm installed:

npm ci
npm run typecheck
npm run build:dev

The output is dist/wiser-zigbee-card.js. The rollup script runs the device-image generation step first. npm run build also runs the project's lint script, which currently invokes Prettier with --write . and can modify files.

Build versions

Build versions are derived from package.json. Successful builds that change the version also update package.json and package-lock.json; review those changes before committing.

Command	Version behaviour
npm run build:dev / npm start	Increment an existing -dev.N; from a beta, advance to the next beta’s -dev.1; from a stable release, start the next patch’s -beta.1-dev.1
npm run rollup / npm run build	Remove the development suffix to produce the corresponding beta or stable version
npm run build:release	Remove beta/development suffixes to produce the final stable version

The old .dev-build.json counter is no longer used. These commands describe the contributor workflow; the user guides document stable 3.0.4. Check out the stable release tag when verifying documented behaviour.

Every build also writes dist/build-info.json with the embedded version and cache-busting dashboard resource URL. Tagged release builds require the GitHub release tag to match the package version exactly.

Compiled bundles include a WISER-CARD-VERSION comment containing the card name and version. The integration uses this marker to update resource URLs without depending on minified variable names or editor text.

For manual development deployment, follow Testing a development build.

Tests

Run the focused regression tests:

npm test

The suite covers layout, area grouping, device details, editor behaviour, localisation, saving, scrolling, link labels, signal colours and the magnifier. Run relevant tests and TypeScript checks when changing the implementation.

Demo

After building:

python3 -m http.server 8127 --bind 127.0.0.1

Open http://127.0.0.1:8127/demo/. Append ?lang=de or ?lang=fr to preview those languages. Use ?theme_mode=light or ?theme_mode=dark to check map appearance, and ?panel=1 for the sidebar host. The demo uses mock network data and helps check layout, local persistence and light/dark colours. Native Home Assistant editor controls and dashboard saves require Home Assistant.

Source map

File	Responsibility
src/wiser-zigbee-card.ts	Rendering, interaction, loading and layout persistence
src/editor.ts	Visual editor and defaults
src/types.ts	Configuration and network types
src/wiser-zigbee-panel.js	Standalone/unified panel host and per-hub settings writes
src/settings-transfer.ts	Copy/Paste YAML validation and coordinates
src/home-assistant-link.ts	Optional Home Assistant connection
scripts/build-version.mjs	Bundle version markers and package version updates
src/data/websockets.ts	Wiser integration requests
src/layout.ts, src/pie-layout.ts	Network arrangements
src/areas.ts, src/area-graph.ts	Home Assistant area matching and grouping
src/device-info.ts	Device/entity matching and reception metrics
src/save-config.ts, src/sanitize-config.ts	Dashboard saving and legacy configuration cleanup
src/localize/	Card translations

See ASSETS.md in the source repository for artwork sources and coverage. Images represent device categories rather than identifying hardware generations.

Maintaining the wiki

The wiki is a separate Git repository, wiser-zigbee-card.wiki.git. Each Markdown file is a page; Home.md is the landing page, _Sidebar.md supplies navigation and _Footer.md supplies shared footer links.

When features change, update the relevant guide and configuration table, and check defaults against the implementation. In particular, verify persistence precedence and copied YAML fields directly in the card code.