@gsxhq/vite-plugin-gsx 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 gsxhq
+
+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,197 @@
+# @gsxhq/vite-plugin-gsx
+
+Vite dev plugin for [gsx](https://github.com/gsxhq/gsx) — watches `.gsx` files, runs `gsx generate`, shows compile errors in the Vite overlay, and triggers a full browser reload after the Go server reboots.
+
+Because gsx renders HTML **server-side**, there is no JavaScript module graph to hot-replace. The plugin does not use Vite HMR; instead it re-generates the `.x.go` files, waits for the Go binary to restart, and then issues a **full-reload** driven by a POST from the Go server — not by the file-change event itself. This keeps the browser tab pointing at a live server, never at stale generated code.
+
+---
+
+## Install
+
+```bash
+npm i -D @gsxhq/vite-plugin-gsx
+```
+
+### Prerequisite: `go tool gsx`
+
+The default command is `go tool gsx generate`. Register the tool in your Go module once:
+
+```bash
+go get -tool github.com/gsxhq/gsx/cmd/gsx
+```
+
+After this, `go tool gsx generate` works without a separate install step and is pinned to your `go.mod` version. If you maintain a custom `cmd/gsx` in your own repo, override the command option instead (see [Options](#options)).
+
+---
+
+## Quick start
+
+```ts
+// vite.config.ts
+import { defineConfig } from "vite";
+import { gsx } from "@gsxhq/vite-plugin-gsx";
+
+// Example dev config: Vite is the front door and proxies non-Vite routes to the
+// Go server, so the injected @vite/client socket survives Go rebuilds.
+export default defineConfig({
+  plugins: [
+    gsx({
+      // Default is ["go","tool","gsx","generate"]; override for a custom cmd/gsx:
+      // command: ["go", "run", "./cmd/gsx", "generate"],
+    }),
+  ],
+  server: {
+    proxy: {
+      "^(?!/@vite|/@id|/node_modules).*": {
+        target: "http://localhost:8080",
+        changeOrigin: true,
+        ws: true,
+      },
+    },
+  },
+});
+```
+
+This config is also present at [`examples/vite.config.ts`](examples/vite.config.ts) and is type-checked on every CI run (`npm run typecheck:example`).
+
+---
+
+## How the loop works
+
+```
+save .gsx file
+    │
+    ▼
+vite-plugin-gsx: watcher fires
+    │  debounce 50 ms
+    ▼
+go tool gsx generate   ← regenerates .x.go files
+    │  ok → nothing broadcast (wait for Go server)
+    │  err → error overlay shown in browser
+    ▼
+wgo / air: detects .go change, rebuilds and restarts Go binary
+    │
+    ▼
+Go binary boots → calls NotifyViteReload(viteDevURL)
+    │  POST /__reload
+    ▼
+vite-plugin-gsx: receives POST → server.ws.send({ type: "full-reload" })
+    │
+    ▼
+browser tab reloads, fetches fresh HTML from the new Go server
+```
+
+**Key invariant:** the browser reload is triggered by the Go POST, not by the `.gsx` file change. The plugin does not broadcast a reload immediately after `gsx generate` succeeds — it waits for the Go server to be up and ready before reloading the browser. This prevents the browser from loading a page from a server that is still mid-restart.
+
+---
+
+## Project-side glue (three pieces)
+
+The plugin handles the Vite side. Your Go project needs three corresponding pieces.
+
+### 1. Proxy
+
+Add the proxy block to your `vite.config.ts` (shown in the quick start above). This makes Vite the front door: asset and HMR WebSocket routes stay with Vite; everything else — your actual HTML pages — is proxied to the Go server on port 8080. The `@vite/client` WebSocket connection is maintained across Go rebuilds because it connects to Vite, not to Go.
+
+```ts
+server: {
+  proxy: {
+    "^(?!/@vite|/@id|/node_modules).*": {
+      target: "http://localhost:8080",
+      changeOrigin: true,
+      ws: true,
+    },
+  },
+},
+```
+
+### 2. `@vite/client` script in the layout
+
+The browser needs the `@vite/client` script to receive the full-reload signal. Inject it in your root layout, gated on a boolean your app controls so the script is never emitted in production:
+
+```gsx
+component Layout(title string) {
+  <head>
+    <title>{title}</title>
+    if dev { <script type="module" src="/@vite/client"></script> }
+  </head>
+}
+```
+
+`dev` is a boolean **you** supply — the plugin does not set or pass any dev flag. Gate it on the same signal as `NotifyViteReload` so the two stay consistent. The natural choice is whether `VITE_DEV_URL` is set (the `NotifyViteReload` snippet already no-ops when it is empty):
+
+```go
+var dev = os.Getenv("VITE_DEV_URL") != ""
+```
+
+Pass `dev` into the layout from your handler. When `VITE_DEV_URL` is unset (production), `dev` is `false`, the `if dev` branch is omitted, and the script tag is never emitted.
+
+### 3. `NotifyViteReload` — Go boot hook
+
+After your Go server starts (or restarts after a wgo rebuild), call `NotifyViteReload` with the Vite dev server URL. This fires a POST to `/__reload`, which the plugin receives and forwards to the browser as a full-reload.
+
+```go
+// NotifyViteReload pokes the Vite dev server after this binary boots so any
+// browser tab holding an @vite/client socket reloads. Dev-only: no-ops when
+// VITE_DEV_URL is unset.
+func NotifyViteReload(viteDevURL string) {
+    if viteDevURL == "" {
+        return
+    }
+    go func() {
+        ctx, cancel := context.WithTimeout(context.Background(), 2*time.Second)
+        defer cancel()
+        for range 10 {
+            req, err := http.NewRequestWithContext(ctx, http.MethodPost, viteDevURL+"/__reload", nil)
+            if err != nil {
+                return
+            }
+            if resp, err := http.DefaultClient.Do(req); err == nil {
+                resp.Body.Close()
+                return
+            }
+            select {
+            case <-ctx.Done():
+                return
+            case <-time.After(150 * time.Millisecond):
+            }
+        }
+    }()
+}
+```
+
+Pass `os.Getenv("VITE_DEV_URL")` (e.g. `http://localhost:5173`) when starting the server in dev mode. In production, leave `VITE_DEV_URL` unset and the function is a no-op.
+
+### `wgo` for Go rebuilds
+
+The plugin only regenerates `.x.go` files; it does not rebuild or restart the Go binary. Use `wgo` (or `air`) to watch `.go` files and rebuild:
+
+```bash
+go tool wgo -file=.go go build -o tmp/app ./cmd/app :: tmp/app
+```
+
+`wgo` rebuilds and restarts `tmp/app` on any `.go` change, including the `.x.go` files that `gsx generate` just wrote. After restart, the new binary calls `NotifyViteReload` and the browser reloads.
+
+---
+
+## Options
+
+All options are optional. Omit them entirely to use the defaults.
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `command` | `string[]` | `["go","tool","gsx","generate"]` | Command and leading args to invoke gsx. Override with `["go","run","./cmd/gsx","generate"]` for a local binary. |
+| `paths` | `string[]` | `["."]` | Path args passed to `generate`. Narrows which packages are regenerated. |
+| `watch` | `string \| string[]` | `"**/*.gsx"` | Glob(s) whose changes trigger regeneration. Relative to the Vite config root. |
+| `cwd` | `string` | Vite config root | Working directory for the generate command. |
+| `reloadEndpoint` | `string` | `"/__reload"` | HTTP endpoint the Go server POSTs to trigger a full browser reload. |
+| `debounce` | `number` | `50` | Debounce window in milliseconds for rapid saves before running generate. |
+| `generateOnStart` | `boolean` | `true` | Run an initial `gsx generate` when the Vite dev server starts, so `.x.go` files exist from the first boot. |
+
+---
+
+## Notes
+
+- **Dev-only.** The plugin sets `apply: "serve"` and is excluded from production builds. It has no effect on `vite build`.
+- **Production generation.** Run `gsx generate` in CI or via a `//go:generate` directive. The plugin is not involved.
+- **Full-reload only.** gsx renders HTML server-side, so there is no JavaScript module graph to partially update. Every change results in a full page reload, not a component-level HMR update.

package/dist/index.d.ts

@@ -0,0 +1,22 @@
+import { Plugin } from 'vite';
+
+interface GsxOptions {
+    /** Command + leading args to invoke gsx. Default: ["go","tool","gsx","generate"]. */
+    command?: string[];
+    /** Path args passed to generate. Default: ["."]. */
+    paths?: string[];
+    /** Globs whose changes trigger regeneration. Default: all .gsx files. */
+    watch?: string | string[];
+    /** Working directory for the command. Default: Vite config root. */
+    cwd?: string;
+    /** Endpoint the Go server POSTs to trigger reload. Default: "/__reload". */
+    reloadEndpoint?: string;
+    /** Debounce window for rapid saves, ms. Default: 50. */
+    debounce?: number;
+    /** Run an initial generate when the dev server starts. Default: true. */
+    generateOnStart?: boolean;
+}
+
+declare function gsx(options?: GsxOptions): Plugin;
+
+export { type GsxOptions, gsx as default, gsx };

package/dist/index.js

@@ -0,0 +1,186 @@
+// src/index.ts
+import { readFileSync } from "fs";
+import { relative } from "path";
+import picomatch from "picomatch";
+
+// src/options.ts
+var DEFAULT_GSX_GLOB = "**/*.gsx";
+function resolveOptions(user, root) {
+  const watch = user.watch === void 0 ? [DEFAULT_GSX_GLOB] : Array.isArray(user.watch) ? user.watch : [user.watch];
+  return {
+    command: user.command ?? ["go", "tool", "gsx", "generate"],
+    paths: user.paths ?? ["."],
+    watch,
+    cwd: user.cwd ?? root,
+    reloadEndpoint: user.reloadEndpoint ?? "/__reload",
+    debounce: user.debounce ?? 50,
+    generateOnStart: user.generateOnStart ?? true
+  };
+}
+
+// src/generate.ts
+import { spawn } from "child_process";
+function runGenerate(opts) {
+  const [bin, ...leading] = opts.command;
+  if (!bin) {
+    return Promise.resolve({
+      ok: false,
+      raw: "",
+      diagnostics: [synthetic("vite-plugin-gsx: empty `command` option")]
+    });
+  }
+  const args = [...leading, "--json", ...opts.paths];
+  return new Promise((resolve) => {
+    let stdout = "";
+    let stderr = "";
+    const child = spawn(bin, args, { cwd: opts.cwd });
+    child.stdout.on("data", (d) => stdout += d.toString());
+    child.stderr.on("data", (d) => stderr += d.toString());
+    child.on("error", (e) => {
+      resolve({
+        ok: false,
+        raw: String(e),
+        diagnostics: [
+          synthetic(
+            `vite-plugin-gsx: could not run gsx (\`${opts.command.join(" ")}\`): ${e.code ?? e.message}. Is the gsx \`tool\` directive in go.mod, and is Go installed?`
+          )
+        ]
+      });
+    });
+    child.on("close", (code) => {
+      if (code === 0) {
+        resolve({ ok: true, diagnostics: [], raw: stdout });
+        return;
+      }
+      const parsed = parseDiagnostics(stdout);
+      if (parsed) {
+        resolve({ ok: false, diagnostics: parsed, raw: stdout });
+        return;
+      }
+      const detail = (stderr || stdout || `exit ${code}`).trim();
+      resolve({
+        ok: false,
+        raw: stdout,
+        diagnostics: [synthetic(`gsx generate failed: ${detail}`)]
+      });
+    });
+  });
+}
+function parseDiagnostics(stdout) {
+  const text = stdout.trim();
+  if (!text.startsWith("[")) return null;
+  try {
+    const arr = JSON.parse(text);
+    if (!Array.isArray(arr)) return null;
+    return arr;
+  } catch {
+    return null;
+  }
+}
+function synthetic(message) {
+  return {
+    file: "",
+    range: { start: { line: 1, col: 1 }, end: { line: 1, col: 1 } },
+    severity: "error",
+    message
+  };
+}
+
+// src/diagnostics.ts
+function toViteError(diags, readSource2) {
+  const err = diags.find((d) => d.severity === "error");
+  if (!err) return null;
+  const head = err.code ? `${err.code}: ${err.message}` : err.message;
+  const message = err.help ? `${head}
+
+${err.help}` : head;
+  return {
+    message,
+    stack: "",
+    id: err.file,
+    frame: buildFrame(err, readSource2),
+    plugin: "vite-plugin-gsx",
+    loc: {
+      file: err.file,
+      line: err.range.start.line,
+      column: err.range.start.col
+    }
+  };
+}
+function buildFrame(diag, readSource2) {
+  const src = readSource2(diag.file);
+  if (src === null) return "";
+  const lines = src.split("\n");
+  const lineNo = diag.range.start.line;
+  const srcLine = lines[lineNo - 1];
+  if (srcLine === void 0) return "";
+  const gutter = `${lineNo} | `;
+  const caretPad = " ".repeat(gutter.length + Math.max(0, diag.range.start.col - 1));
+  return `${gutter}${srcLine}
+${caretPad}^`;
+}
+
+// src/index.ts
+function gsx(options = {}) {
+  return {
+    name: "vite-plugin-gsx",
+    apply: "serve",
+    configureServer(server) {
+      const opts = resolveOptions(options, server.config.root);
+      const isMatch = picomatch(opts.watch);
+      const logger = server.config.logger;
+      server.middlewares.use(opts.reloadEndpoint, (req, res) => {
+        if (req.method !== "POST") {
+          res.statusCode = 405;
+          res.end();
+          return;
+        }
+        server.ws.send({ type: "full-reload", path: "*" });
+        res.statusCode = 204;
+        res.end();
+      });
+      async function generate() {
+        const result = await runGenerate({
+          command: opts.command,
+          paths: opts.paths,
+          cwd: opts.cwd
+        });
+        if (result.ok) return;
+        const err = toViteError(result.diagnostics, readSource);
+        if (err) {
+          for (const d of result.diagnostics) {
+            logger.error(`[vite-plugin-gsx] ${d.file}: ${d.message}`, {
+              timestamp: true
+            });
+          }
+          server.ws.send({ type: "error", err });
+        }
+      }
+      let timer;
+      function schedule() {
+        if (timer) clearTimeout(timer);
+        timer = setTimeout(() => void generate(), opts.debounce);
+      }
+      function onChange(file) {
+        if (isMatch(relative(opts.cwd, file))) schedule();
+      }
+      server.watcher.on("change", onChange);
+      server.watcher.on("add", onChange);
+      server.watcher.on("unlink", onChange);
+      if (opts.generateOnStart) void generate();
+    }
+  };
+}
+function readSource(file) {
+  if (!file) return null;
+  try {
+    return readFileSync(file, "utf8");
+  } catch {
+    return null;
+  }
+}
+var index_default = gsx;
+export {
+  index_default as default,
+  gsx
+};

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@gsxhq/vite-plugin-gsx",
+  "version": "0.1.0",
+  "description": "Vite dev plugin for gsx: watch .gsx, regenerate, error overlay, browser reload.",
+  "type": "module",
+  "license": "MIT",
+  "engines": { "node": ">=18" },
+  "repository": { "type": "git", "url": "git+https://github.com/gsxhq/vite-plugin-gsx.git" },
+  "homepage": "https://github.com/gsxhq/vite-plugin-gsx#readme",
+  "publishConfig": { "access": "public" },
+  "files": ["dist"],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "scripts": {
+    "build": "tsup",
+    "prepublishOnly": "npm run build",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit",
+    "typecheck:example": "tsc --noEmit -p examples/tsconfig.json"
+  },
+  "peerDependencies": {
+    "vite": "^5.0.0 || ^6.0.0 || ^7.0.0"
+  },
+  "dependencies": {
+    "picomatch": "^4.0.2"
+  },
+  "devDependencies": {
+    "@types/node": "^20.14.0",
+    "@types/picomatch": "^3.0.1",
+    "tsup": "^8.3.0",
+    "typescript": "^5.6.0",
+    "vite": "^6.0.0",
+    "vitest": "^2.1.0"
+  }
+}