@cequrebackends/plugin-vite 0.13.0

package/README.md

@@ -0,0 +1,63 @@
+# @cequrebackends/plugin-vite
+
+Vite dev server integration plugin for Cequre backends. Bridge your Cequre backend and Vite frontend into a single seamless dev server on the same port.
+
+## Installation
+
+```bash
+bun add @cequrebackends/plugin-vite
+```
+
+## Usage
+
+### Zero Config (Dev Mode)
+
+```typescript
+// vite.config.ts
+import { defineConfig } from "vite";
+import react from "@vitejs/plugin-react";
+import { cequreVite } from "@cequrebackends/plugin-vite";
+
+export default defineConfig({
+  plugins: [
+    react(),
+    cequreVite()
+  ]
+});
+```
+
+### Full-Stack Build (`autoBuild: true`)
+
+```typescript
+// vite.config.ts
+import { defineConfig } from "vite";
+import react from "@vitejs/plugin-react";
+import { cequreVite } from "@cequrebackends/plugin-vite";
+
+export default defineConfig({
+  plugins: [
+    react(),
+    cequreVite({
+      autoBuild: true // Bundles Cequre backend into build/server/server.js on `vite build`
+    })
+  ]
+});
+```
+
+## Features
+
+- **Single-Port Parity**: Proxies HTTP and WebSockets (`ws: true`) from Vite to Cequre automatically under `/api`.
+- **Fast Execution**: Probes local `node_modules/.bin/cequre` to bypass `bunx` startup latency.
+- **Auto Entry Detection**: Finds your Cequre backend entry point automatically.
+- **SDK Watcher**: Triggers Vite HMR reloads automatically when Cequre generates updated `client.ts` / SDK files.
+- **Unified Build**: Set `autoBuild: true` to bundle backend server output automatically during `vite build`.
+
+## WebSocket & SSE Support
+
+WebSocket proxying is enabled **automatically by default under the hood**. No configuration options are needed in `cequreVite()`. In your frontend, connect directly using relative URLs over Vite's dev port:
+
+```typescript
+const protocol = window.location.protocol === "https:" ? "wss:" : "ws:";
+const socket = new WebSocket(`${protocol}//${window.location.host}/api/ws`);
+```
+

package/dist/index.d.ts

@@ -0,0 +1,26 @@
+import type { Plugin } from "vite";
+export interface CequreViteOptions {
+    /** URL prefix for API routes. Defaults to `"/api"`. */
+    apiPrefix?: string;
+    /** Custom entry point for the Cequre server. Defaults to auto-detecting `src/server/index.ts`, `server/index.ts`, `src/index.ts`, or `api/index.ts`. */
+    entry?: string;
+    /** Automatically run backend production build during Vite build closeBundle hook. Defaults to `false`. */
+    autoBuild?: boolean;
+}
+export declare function resolveApiPrefix(customPrefix?: string): string;
+export declare function resolveEntryPoint(customEntry?: string): string;
+export declare function getExecutableCommand(): {
+    command: string;
+    argsPrefix: string[];
+};
+export declare function cequreVite(options?: CequreViteOptions): Plugin;
+export declare namespace cequreVite {
+    var build: (options?: CequreViteBuildOptions) => Promise<void>;
+}
+export interface CequreViteBuildOptions {
+    entry?: string;
+    outDir?: string;
+    outFile?: string;
+    minify?: boolean;
+}
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAiB,MAAM,MAAM,CAAC;AAMlD,MAAM,WAAW,iBAAiB;IAChC,uDAAuD;IACvD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,wJAAwJ;IACxJ,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,0GAA0G;IAC1G,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AAOD,wBAAgB,gBAAgB,CAAC,YAAY,CAAC,EAAE,MAAM,GAAG,MAAM,CAoC9D;AAED,wBAAgB,iBAAiB,CAAC,WAAW,CAAC,EAAE,MAAM,GAAG,MAAM,CAkB9D;AAED,wBAAgB,oBAAoB,IAAI;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,MAAM,EAAE,CAAA;CAAE,CAMhF;AAqBD,wBAAgB,UAAU,CAAC,OAAO,GAAE,iBAAsB,GAAG,MAAM,CAmMlE;yBAnMe,UAAU;0BA4MkB,sBAAsB;;AAPlE,MAAM,WAAW,sBAAsB;IACrC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB"}

package/dist/index.js

@@ -0,0 +1,316 @@
+// @bun
+var __require = import.meta.require;
+
+// src/index.ts
+import { spawn, execSync } from "child_process";
+import path from "path";
+import fs from "fs";
+import os from "os";
+var g = globalThis;
+var globalWsPort = g.__CEQURE_WS_PORT || 0;
+var globalCequreProcess = g.__CEQURE_PROCESS || null;
+var globalCleanupRegistered = g.__CEQURE_CLEANUP || false;
+function resolveApiPrefix(customPrefix) {
+  if (customPrefix) {
+    return customPrefix.startsWith("/") ? customPrefix : "/" + customPrefix;
+  }
+  const schemaPath = path.resolve(process.cwd(), "node_modules", ".cequre", "schema.json");
+  if (fs.existsSync(schemaPath)) {
+    try {
+      const schema = JSON.parse(fs.readFileSync(schemaPath, "utf-8"));
+      if (schema.core?.api?.prefix) {
+        const prefix = schema.core.api.prefix;
+        return prefix.startsWith("/") ? prefix : "/" + prefix;
+      }
+    } catch {}
+  }
+  const cequreDir = path.resolve(process.cwd(), "cequre");
+  if (fs.existsSync(cequreDir)) {
+    try {
+      const files = fs.readdirSync(cequreDir);
+      for (const f of files) {
+        if (f.endsWith(".cequre")) {
+          const content = fs.readFileSync(path.join(cequreDir, f), "utf-8");
+          const match = content.match(/prefix:\s*["']([^"']+)["']/);
+          if (match && match[1]) {
+            const prefix = match[1];
+            return prefix.startsWith("/") ? prefix : "/" + prefix;
+          }
+        }
+      }
+    } catch {}
+  }
+  return "/api";
+}
+function resolveEntryPoint(customEntry) {
+  if (customEntry) {
+    return customEntry;
+  }
+  const candidates = [
+    "src/server/app.ts",
+    "src/app.ts",
+    "src/server/index.ts",
+    "server/index.ts",
+    "src/index.ts",
+    "api/index.ts"
+  ];
+  for (const cand of candidates) {
+    if (fs.existsSync(path.resolve(process.cwd(), cand))) {
+      return cand;
+    }
+  }
+  return "src/index.ts";
+}
+function getExecutableCommand() {
+  const localBin = path.join(process.cwd(), "node_modules", ".bin", "cequre");
+  if (fs.existsSync(localBin)) {
+    return { command: localBin, argsPrefix: [] };
+  }
+  return { command: "bunx", argsPrefix: ["cequre"] };
+}
+function tryAcquireLock() {
+  if (!globalWsPort)
+    return false;
+  const lockPath = path.join(os.tmpdir(), `cequre-dev-${globalWsPort}.lock`);
+  try {
+    const fd = fs.openSync(lockPath, "wx");
+    fs.closeSync(fd);
+    return true;
+  } catch (e) {
+    if (e.code === "EEXIST")
+      return false;
+    throw e;
+  }
+}
+function releaseLock() {
+  if (!globalWsPort)
+    return;
+  const lockPath = path.join(os.tmpdir(), `cequre-dev-${globalWsPort}.lock`);
+  try {
+    fs.unlinkSync(lockPath);
+  } catch {}
+}
+function cequreVite(options = {}) {
+  let resolvedApiPrefix = resolveApiPrefix(options.apiPrefix);
+  if (!globalCleanupRegistered) {
+    globalCleanupRegistered = true;
+    g.__CEQURE_CLEANUP = true;
+    const cleanup = () => {
+      if (globalCequreProcess) {
+        globalCequreProcess.kill("SIGTERM");
+        globalCequreProcess = null;
+        g.__CEQURE_PROCESS = null;
+      }
+      releaseLock();
+    };
+    process.on("beforeExit", cleanup);
+    process.on("exit", cleanup);
+  }
+  return {
+    name: "cequre-vite-plugin",
+    async config(config, env) {
+      if (env.command === "serve") {
+        resolvedApiPrefix = resolveApiPrefix(options.apiPrefix);
+        const envPort = process.env.CEQURE_DEV_PORT;
+        if (envPort) {
+          globalWsPort = parseInt(envPort, 10);
+          g.__CEQURE_WS_PORT = globalWsPort;
+        } else if (!globalWsPort) {
+          const net = await import("net");
+          for (let port = 3001;port < 3100; port++) {
+            try {
+              await new Promise((resolve, reject) => {
+                const srv = net.createServer();
+                srv.unref();
+                srv.on("error", reject);
+                srv.listen(port, "127.0.0.1", () => {
+                  srv.close(resolve);
+                });
+              });
+              globalWsPort = port;
+              g.__CEQURE_WS_PORT = port;
+              releaseLock();
+              break;
+            } catch (e) {}
+          }
+          if (!globalWsPort) {
+            throw new Error("[cequre.vite] No available port found in range 3001-3099. Set CEQURE_DEV_PORT env var or free a port in this range.");
+          }
+        }
+        const viteConfig = {
+          define: {
+            __CEQURE_DEV_WS_URL__: JSON.stringify(`ws://127.0.0.1:${globalWsPort}`)
+          },
+          server: {
+            proxy: {
+              [resolvedApiPrefix]: {
+                target: `http://127.0.0.1:${globalWsPort}`,
+                changeOrigin: true,
+                ws: true,
+                configure: (proxy, _options) => {
+                  proxy.on("proxyReq", (proxyReq, req) => {
+                    if (req && req.headers && req.headers.host) {
+                      proxyReq.setHeader("x-forwarded-host", req.headers.host);
+                      proxyReq.setHeader("x-forwarded-proto", req.socket?.encrypted ? "https" : "http");
+                    }
+                  });
+                  const originalEmit = proxy.emit.bind(proxy);
+                  proxy.emit = function(event, ...args) {
+                    if (event === "error" && args[0] && args[0].code === "ECONNREFUSED") {
+                      const res = args[2];
+                      if (res && !res.headersSent && typeof res.writeHead === "function") {
+                        res.writeHead(503, {
+                          "Content-Type": "application/json",
+                          "Retry-After": "1"
+                        });
+                        res.end(JSON.stringify({ error: "Cequre backend restarting", code: "ECONNREFUSED_CEQURE" }));
+                      }
+                      return false;
+                    }
+                    return originalEmit(event, ...args);
+                  };
+                }
+              }
+            }
+          }
+        };
+        return viteConfig;
+      }
+      return {};
+    },
+    async configureServer(server) {
+      const envName = server.environment?.name ?? server.config?.environments?.client?.name ?? "";
+      if (envName && envName !== "client")
+        return;
+      const spawnCequre = () => {
+        if (globalCequreProcess || !tryAcquireLock()) {
+          return;
+        }
+        const resolvedEntry = resolveEntryPoint(options.entry);
+        const exec = getExecutableCommand();
+        const args = [...exec.argsPrefix, "dev"];
+        if (resolvedEntry) {
+          args.push("--entry", resolvedEntry);
+        }
+        server.config.logger.info(`[cequre.vite] Attached Cequre API (${resolvedApiPrefix}) to Vite host.`);
+        globalCequreProcess = spawn(exec.command, args, {
+          cwd: process.cwd(),
+          stdio: "pipe",
+          env: { ...process.env, PORT: String(globalWsPort), HOST: "127.0.0.1", CEQURE_VITE_MODE: "1" }
+        });
+        g.__CEQURE_PROCESS = globalCequreProcess;
+        globalCequreProcess.stdout?.on("data", (data) => {
+          const msg = data.toString().trim();
+          if (msg && !msg.includes("Starting Bun dev server") && !msg.includes("URL:") && !msg.includes("starting on http") && !msg.includes("started gracefully on port") && !msg.includes(`:${globalWsPort}`)) {
+            server.config.logger.info(`[cequre] ${msg}`);
+          }
+        });
+        globalCequreProcess.stderr?.on("data", (data) => {
+          const msg = data.toString().trim();
+          if (msg) {
+            server.config.logger.error(`[cequre] ${msg}`);
+          }
+        });
+        globalCequreProcess.on("close", (code) => {
+          if (code !== 0 && code !== null) {
+            server.config.logger.error(`[cequre.vite] Cequre binary exited with code ${code}`);
+          }
+          globalCequreProcess = null;
+          g.__CEQURE_PROCESS = null;
+          releaseLock();
+        });
+      };
+      const cequrePaths = [
+        path.resolve(process.cwd(), "cequre"),
+        path.resolve(process.cwd(), "src/server"),
+        path.resolve(process.cwd(), "src/routes"),
+        path.resolve(process.cwd(), "cequre.config.json")
+      ].filter((p) => fs.existsSync(p));
+      if (cequrePaths.length > 0) {
+        server.watcher.add(cequrePaths);
+      }
+      server.watcher.on("change", (filePath) => {
+        if (filePath.endsWith("client.ts") || filePath.endsWith("sdk.ts") || filePath.includes("cequre-generated") || filePath.includes("cequre") || filePath.includes("server") || filePath.includes("routes")) {
+          server.config.logger.info(`[cequre.vite] Backend / SDK updated (${path.basename(filePath)}), triggering Vite HMR reload`);
+          server.ws.send({ type: "full-reload" });
+        }
+      });
+      if (server.httpServer?.listening) {
+        spawnCequre();
+      } else {
+        server.httpServer?.once("listening", spawnCequre);
+      }
+    },
+    async closeBundle() {
+      if (options.autoBuild) {
+        const resolvedEntry = resolveEntryPoint(options.entry);
+        await cequreVite.build({ entry: resolvedEntry });
+      }
+    }
+  };
+}
+cequreVite.build = async function(options = {}) {
+  const entry = resolveEntryPoint(options.entry);
+  const outDir = options.outDir || "build/server";
+  const minify = options.minify !== false;
+  console.log(`[cequre.vite] Starting production build...`);
+  const absEntry = path.resolve(process.cwd(), entry);
+  if (!fs.existsSync(absEntry)) {
+    throw new Error(`[cequre.vite] Entry point not found: ${absEntry}`);
+  }
+  let buildOutDir;
+  let naming;
+  if (options.outFile) {
+    const absOutFile = path.resolve(process.cwd(), options.outFile);
+    buildOutDir = path.dirname(absOutFile);
+    naming = path.basename(absOutFile);
+  } else {
+    buildOutDir = path.resolve(process.cwd(), outDir);
+    naming = "server.js";
+  }
+  if (!fs.existsSync(buildOutDir)) {
+    fs.mkdirSync(buildOutDir, { recursive: true });
+  }
+  console.log(`[cequre.vite] Bundling Cequre API with Bun...`);
+  const targetOutputPath = path.join(buildOutDir, naming);
+  if (typeof Bun !== "undefined") {
+    const buildResult = await Bun.build({
+      entrypoints: [absEntry],
+      outdir: buildOutDir,
+      naming,
+      target: "bun",
+      minify
+    });
+    if (!buildResult.success) {
+      const errorDetails = buildResult.logs.map((log) => typeof log === "string" ? log : `${log.message ?? ""} (${log.position?.file ?? "?"}:${log.position?.line ?? "?"})`).join(`
+`);
+      throw new Error(`[cequre.vite] Bun.build failed:
+${errorDetails}`);
+    }
+  } else {
+    const localBin = path.join(process.cwd(), "node_modules", ".bin", "bun");
+    const bunCmd = fs.existsSync(localBin) ? localBin : "bun";
+    const minifyFlag = minify ? " --minify" : "";
+    try {
+      execSync(`${bunCmd} build "${absEntry}" --outfile "${targetOutputPath}" --target bun${minifyFlag}`, {
+        stdio: "inherit",
+        env: process.env
+      });
+    } catch (err) {
+      throw new Error(`[cequre.vite] Bundling Cequre API failed using '${bunCmd}'. Ensure Bun is installed on your system or run builds using Bun ('bun run build'). Error: ${err.message}`);
+    }
+  }
+  const entryBasename = path.basename(absEntry, path.extname(absEntry)) + ".js";
+  const entryFallbackPath = path.join(buildOutDir, entryBasename);
+  const actualPath = fs.existsSync(targetOutputPath) ? targetOutputPath : fs.existsSync(entryFallbackPath) ? entryFallbackPath : targetOutputPath;
+  console.log(`[cequre.vite] API bundled successfully to: ${actualPath}`);
+  if (!fs.existsSync(actualPath)) {
+    throw new Error(`[cequre.vite] Build reported success but output not found: ${actualPath}`);
+  }
+};
+export {
+  resolveEntryPoint,
+  resolveApiPrefix,
+  getExecutableCommand,
+  cequreVite
+};

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@cequrebackends/plugin-vite",
+  "version": "0.13.0",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "rm -rf dist && bun build ./src/index.ts --outdir ./dist --target bun --packages external && tsc --emitDeclarationOnly",
+    "dev": "bun build ./src/index.ts --outdir ./dist --target bun --packages external --watch"
+  },
+  "peerDependencies": {
+    "vite": "8.1.5",
+    "@cequrebackends/cequre-ts": "^0.13.0"
+  },
+  "devDependencies": {
+    "typescript": "^7.0.2",
+    "vite": "^8.1.5",
+    "@types/node": "^26.1.1",
+    "@types/bun": "latest",
+    "@cequrebackends/cequre-ts": "^0.13.0"
+  },
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/cequrebackends/cequre.git"
+  }
+}