@hummingbirdworks/proxy 0.1.0 → 0.2.0

package/README.md

@@ -127,14 +127,70 @@ instructions for your OS/browser.
   open DevTools → Application → Service Workers and check "Bypass for network"
   to disable the service worker cache.
 
-## Config reference (CLI / env)
+## Using with Vite (HMR)
+
+A `devserver` rule routes a web resource's requests to a running Vite dev
+server, giving you hot module reload on the Dynamics-hosted page.
+
+The dev server can stay on plain HTTP — the browser only talks to the proxy, and
+the proxy relays requests (including the HMR websocket) to `localhost`. Because
+the Dynamics page is HTTPS, the browser would block an insecure `ws://` HMR
+socket as mixed content, so point the HMR client at `wss` and let the proxy
+forward it to the HTTP dev server. No dev-server cert (or `vite-plugin-mkcert`)
+is needed.
+
+### Vite config
+
+The package ships a Vite plugin that helps with the configuration of web resources. 
+It sets the base path, configures settings to support HMR with the proxy, and turns
+off cache busting since powerapps already has cache busting when you publish customizations.
+
+```ts
+import { defineConfig } from 'vite'
+import { svelte } from '@sveltejs/vite-plugin-svelte'
+import { powerAppsWebResource } from '@hummingbirdworks/proxy/vite'
+
+export default defineConfig({
+  plugins: [
+    svelte(), // or react(), vue(), etc.
+    powerAppsWebResource({ prefix: 'test_/myapp/' }),
+  ],
+  server: { port: 5173 },
+})
+```
 
-- **Config path resolution:** the CLI uses the first non-flag argument as the
-  config path, defaulting to `./proxy.config.toml` in the current directory. It
-  passes the resolved absolute path to the addon via the
-  `HUMMINGBIRD_PROXY_CONFIG` environment variable.
-- **Running the addon directly** (without the CLI) is also supported:
+Options:
 
-  ```sh
-  HUMMINGBIRD_PROXY_CONFIG=/abs/path/proxy.config.toml mitmdump -s powerapp_dev_proxy.py
-  ```
+- `prefix` (required): the web resource path, e.g. `test_/myapp/`.
+- `hmrClientPort` (default `443`): port the browser uses for the HMR socket.
+- `stableFilenames` (default `true`): emit unhashed filenames and a single
+  stylesheet. Set `false` to keep Vite's defaults.
+
+If your HTML entry isn't `index.html`, add it to `build.rollupOptions.input`.
+
+### Proxy rule
+
+Point a `devserver` rule at the dev server. The `url` scheme/port must match
+what Vite serves (`http://localhost:5173` by default here):
+
+```toml
+[[rules]]
+type = "devserver"
+name = "test_/myapp/"
+url = "http://localhost:5173"
+domain = "myorg.crm.dynamics.com"
+```
+
+### Run
+
+Start the dev server and the proxy, then browse through the proxy:
+
+```sh
+npm run dev
+npm run proxy
+```
+
+Open the Dynamics page hosting the web resource. Edit → save → the page updates
+without a manual refresh. If HMR doesn't trigger, confirm Vite's port matches
+the rule `url`, that the HMR socket connects over `wss`, and that the service
+worker cache is bypassed (see Notes above).

package/package.json

@@ -1,12 +1,20 @@
 {
   "name": "@hummingbirdworks/proxy",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "mitmproxy-based dev proxy that redirects Dataverse / Dynamics 365 web resources and PCF control assets to local dev builds or a running dev server.",
   "bin": {
     "hummingbird-proxy": "bin/hummingbird-proxy.js"
   },
+  "exports": {
+    "./vite": {
+      "types": "./vite/index.d.ts",
+      "default": "./vite/index.js"
+    },
+    "./package.json": "./package.json"
+  },
   "files": [
     "bin/",
+    "vite/",
     "powerapp_dev_proxy.py",
     "proxy.config.example.toml",
     "README.md"
@@ -14,6 +22,14 @@
   "engines": {
     "node": ">=16"
   },
+  "peerDependencies": {
+    "vite": ">=4"
+  },
+  "peerDependenciesMeta": {
+    "vite": {
+      "optional": true
+    }
+  },
   "keywords": [
     "mitmproxy",
     "powerapps",

package/powerapp_dev_proxy.py

@@ -184,7 +184,12 @@ def _web_resource_name(request: http.Request) -> str | None:
     components = request.path_components
     for i, component in enumerate(components):
         if component.lower() == "webresources":
-            return "/".join(components[i + 1:])
+            name = "/".join(components[i + 1:])
+            # path_components drops a trailing slash; keep it so dev-server root
+            # requests (e.g. the Vite HMR base URL) still match a rule prefix.
+            if name and request.path.split("?", 1)[0].endswith("/"):
+                name += "/"
+            return name
     return None
 
 

package/vite/index.d.ts

@@ -0,0 +1,22 @@
+import type { Plugin } from "vite";
+
+export interface WebResourceOptions {
+  /** Web resource path prefix, e.g. `test_/myapp/`. Leading/trailing slashes are optional. */
+  prefix: string;
+  /** Port the browser uses for the HMR websocket. Defaults to `443`. */
+  hmrClientPort?: number;
+  /**
+   * Emit unhashed filenames and a single stylesheet so solution components stay
+   * stable across builds. Defaults to `true`; set `false` to keep Vite's defaults.
+   */
+  stableFilenames?: boolean;
+}
+
+/**
+ * Vite plugin that aligns the dev server and build output with a Dataverse /
+ * Dynamics 365 web resource served through `@hummingbirdworks/proxy`.
+ *
+ * Sets `base` (absolute in dev, relative in build) and a `wss` HMR socket, and
+ * optionally emits stable filenames.
+ */
+export function powerAppsWebResource(options: WebResourceOptions): Plugin;

package/vite/index.js

@@ -0,0 +1,49 @@
+"use strict";
+
+// Vite plugin that configures a project so its dev server and build output line
+// up with a Dataverse / Dynamics 365 web resource served through the proxy.
+
+function powerAppsWebResource(options) {
+  if (!options || typeof options.prefix !== "string") {
+    throw new Error(
+      "powerAppsWebResource: 'prefix' is required, e.g. 'test_/myapp/'."
+    );
+  }
+  const prefix = options.prefix.replace(/^\/+|\/+$/g, "");
+  if (!prefix) {
+    throw new Error(
+      "powerAppsWebResource: 'prefix' must not be empty, e.g. 'test_/myapp/'."
+    );
+  }
+  const clientPort = options.hmrClientPort != null ? options.hmrClientPort : 443;
+  const stableFilenames = options.stableFilenames !== false;
+
+  return {
+    name: "@hummingbirdworks/proxy:webresource",
+    config(_config, env) {
+      const isServe = env.command === "serve";
+      // Dynamics pages are HTTPS, so the HMR socket must be wss to avoid
+      // mixed-content blocking; the proxy relays it to the HTTP dev server.
+      const config = {
+        base: isServe ? "/webresources/" + prefix + "/" : "./",
+        server: { hmr: { protocol: "wss", clientPort: clientPort } },
+      };
+      if (stableFilenames) {
+        config.build = {
+          cssCodeSplit: false,
+          rollupOptions: {
+            output: {
+              // Stable filenames — Dynamics does its own cache busting on publish.
+              entryFileNames: "[name].js",
+              chunkFileNames: "[name].js",
+              assetFileNames: "[name].[ext]",
+            },
+          },
+        };
+      }
+      return config;
+    },
+  };
+}
+
+exports.powerAppsWebResource = powerAppsWebResource;