vite-hmr-tchmi 1.0.0

package/.github/workflows/publish.yml

@@ -0,0 +1,28 @@
+name: Publish to npm
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  build-and-publish:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          registry-url: 'https://registry.npmjs.org'
+
+      - name: Install dependencies
+        run: npm install
+
+      - name: Build project
+        run: npm run build
+
+      - name: Publish to npm
+        run: npm publish
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Robin Pichel
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/Readme.md

@@ -0,0 +1,71 @@
+# tchmi-vite-hmr
+
+A utility library to enable Hot Module Replacement (HMR) for Beckhoff TwinCAT HMI (TcHmi) Framework Controls when using Vite.
+
+---
+
+## Disclaimer
+
+**This is not an official Beckhoff product.** This project is a community-maintained tool. "TwinCAT" and "Beckhoff" are registered trademarks of Beckhoff Automation GmbH & Co. KG.
+
+---
+
+## Description
+
+This package provides the necessary logic to hot-reload TcHmi Controls without refreshing the entire browser page. It works by:
+
+* **Prototype Patching:** Dynamically updating the control's logic while preserving the internal state where possible.
+* **Lifecycle Management:** Automatically triggering `__detach()` and `__attach()` to re-render the control in the DOM.
+* **Seamless Integration:** Designed to work specifically with Vite's `import.meta.hot` API.
+
+---
+
+## Installation
+
+```bash
+npm install tchmi-vite-hmr --save-dev
+```
+
+---
+
+## Usage
+
+In your TcHmi Control script file, import the handler and call it within the Vite HMR lifecycle:
+```ts
+import { handleTcHmiHmr } from 'tchmi-vite-hmr';
+
+// ... Your Control Class Definition ...
+export class MyCustomControl extends TcHmi.Controls.System.TcHmiControl {
+    // ...
+}
+
+// Enable HMR for this module
+if (import.meta.hot) import.meta.hot.accept((newModule) => handleTcHmiHmr(newModule));
+```
+
+---
+
+Hier ist der restliche Teil der README ab How it works im Markdown-Format zum Kopieren:
+
+Markdown
+
+## How it works
+
+When a file change is detected, Vite provides the updated module. The `handleTcHmiHmr` function:
+1. **Module Scanning:** Scans the new module for classes extending `TcHmiControl`.
+2. **Instance Mapping:** Locates all active instances of these controls in the current `TcHmi.Controls.getMap()`.
+3. **Detaching:** Calls `__detach()` on each instance to cleanly stop its current lifecycle.
+4. **Prototype Patching:** Swaps the internal prototype of the existing instance with the new logic from the updated module.
+5. **Re-Attaching:** Calls `__attach()` to re-render the control and restart its lifecycle with the new code.
+
+---
+
+## API Reference
+
+### `handleTcHmiHmr(newModule: any): void`
+
+The main entry point for patching controls.
+
+| Parameter | Type | Description |
+| :--- | :--- | :--- |
+| `newModule` | `any` | The module object provided by `import.meta.hot.accept`. |

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "vite-hmr-tchmi",
+  "private": false,
+  "version": "1.0.0",
+  "type": "module",
+  "scripts": {
+    "dev": "tsc --watch",
+    "build": "tsc && vite build"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/robinpichel/vite-hmr-tchmi.git"
+  },
+  "keywords": [
+    "beckhoff",
+    "twincat",
+    "tchmi",
+    "vite",
+    "hmr"
+  ],
+  "author": "Robin Pichel",
+  "license": "MIT",
+  "peerDependencies": {
+    "vite": "^6.0.0 || ^7.0.0"
+  },
+  "devDependencies": {
+    "typescript": "~5.9.3",
+    "vite": "npm:rolldown-vite@7.2.5"
+  },
+  "overrides": {
+    "vite": "npm:rolldown-vite@7.2.5"
+  }
+}

package/src/index.ts

@@ -0,0 +1,46 @@
+function isClassExtending(targetClass: any, baseClass: any) {
+    if (!targetClass || !baseClass) return false;
+
+    const baseName = typeof baseClass === 'string' ? baseClass : baseClass.name;
+
+    let current = targetClass;
+    while (current !== null && current !== undefined) {
+        if (current === baseClass) return true;
+        if (current.constructor.name === baseName) return true;
+
+        current = Object.getPrototypeOf(current);
+    }
+    return false;
+}
+
+export function handleTcHmiHmr(newModule: any) {
+
+    if (!newModule) return;
+
+    for (const [_, newModuleElement] of Object.entries(newModule)) {
+        if (!(isClassExtending(newModuleElement, "TcHmi.Controls.System.TcHmiControl"))) continue;
+        const newControl = newModuleElement as any;
+
+        const instances = Array.from((window as any).TcHmi.Controls.getMap())
+            .filter(([_, inst]: any) => isClassExtending(inst, newControl)) as any[];
+
+        console.groupCollapsed(`🔥 HMR: Updated '${newControl.name}' with ${instances.length} instances.`);
+
+        for (const [id, instance] of instances) {
+            instance.__detach();
+            Object.setPrototypeOf(instance, newControl.prototype);
+            instance.__attach();
+
+            const logHelper = {
+                type: instance.getType(),
+                dom: instance.getElement()[0],
+                instance: instance,
+                [Symbol.toStringTag]: `✅ Patched & Reattached: '${id}'`
+            }
+            console.dir(logHelper);
+        }
+
+        console.groupEnd();
+    }
+    
+}

package/tsconfig.json

@@ -0,0 +1,28 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "useDefineForClassFields": true,
+    "module": "ESNext",
+    "lib": ["ES2022", "DOM", "DOM.Iterable"],
+    "types": ["vite/client"],
+    "skipLibCheck": true,
+
+    "moduleResolution": "bundler",
+    "allowImportingTsExtensions": true,
+    "verbatimModuleSyntax": true,
+    "moduleDetection": "force",
+
+    "noEmit": false,
+    "outDir": "dist",
+    "declaration": true,
+    "emitDeclarationOnly": true,
+
+    "strict": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "erasableSyntaxOnly": true,
+    "noFallthroughCasesInSwitch": true,
+    "noUncheckedSideEffectImports": true
+  },
+  "include": ["src"]
+}

package/vite.config.ts

@@ -0,0 +1,25 @@
+import { defineConfig } from 'vite';
+import { resolve } from 'path';
+
+export default defineConfig({
+    build: {
+        ssr: true,
+        lib: {
+            entry: resolve(__dirname, 'src/index.ts'),
+            name: 'ViteHmrTcHmi',
+            fileName: 'index',
+            formats: ['es']
+        },
+        rollupOptions: {
+            external: [
+                'vite',
+            ],
+            output: {
+                globals: {
+                    vite: 'Vite'
+                }
+            }
+        },
+        minify: true
+    }
+});