@shiftapi/vite-plugin 0.0.1

package/README.md

@@ -0,0 +1,82 @@
+<p align="center">
+	<img src="https://raw.githubusercontent.com/fcjr/shiftapi/main/assets/logo.svg" alt="ShiftAPI Logo">
+</p>
+
+# @shiftapi/vite-plugin
+
+Vite plugin that generates fully-typed TypeScript clients from [ShiftAPI](https://github.com/fcjr/shiftapi) Go servers. Get end-to-end type safety between your Go API and your frontend with zero manual type definitions.
+
+## How it works
+
+1. Extracts the OpenAPI 3.1 spec from your Go server at build time
+2. Generates TypeScript types using `openapi-typescript`
+3. Provides a virtual `@shiftapi/client` module with a pre-configured, fully-typed API client
+4. In dev mode, watches `.go` files and regenerates types on changes
+5. Auto-configures Vite's dev server proxy to forward API requests to your Go server
+
+## Installation
+
+```bash
+npm install -D @shiftapi/vite-plugin
+# or
+pnpm add -D @shiftapi/vite-plugin
+```
+
+**Peer dependency:** `vite` (v5 or v6).
+
+## Setup
+
+### vite.config.ts
+
+```ts
+import { defineConfig } from "vite";
+import shiftapi from "@shiftapi/vite-plugin";
+
+export default defineConfig({
+  plugins: [
+    shiftapi({
+      server: "./cmd/server",
+    }),
+  ],
+});
+```
+
+### Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `server` | `string` | **(required)** | Path to the Go server entry point (e.g. `"./cmd/server"` or `"./cmd/server/main.go"`) |
+| `baseUrl` | `string` | `"/"` | Fallback base URL for the API client. Can be overridden via the `VITE_SHIFTAPI_BASE_URL` env var. |
+| `goRoot` | `string` | `process.cwd()` | Working directory for `go run` |
+| `url` | `string` | `"http://localhost:8080"` | Address the Go server listens on. Used to auto-configure the Vite dev proxy. |
+
+## Usage
+
+Import the typed client in your frontend code:
+
+```ts
+import { client } from "@shiftapi/client";
+
+const { data, error } = await client.GET("/greet", {
+  params: { query: { name: "World" } },
+});
+// `data` and `error` are fully typed based on your Go handler signatures
+```
+
+The `createClient` factory is also exported if you need a custom instance:
+
+```ts
+import { createClient } from "@shiftapi/client";
+
+const api = createClient({ baseUrl: "https://api.example.com" });
+```
+
+## What it auto-configures
+
+- **Vite proxy** -- API paths discovered from your OpenAPI spec are automatically proxied to your Go server during development.
+- **tsconfig.json** -- A path mapping for `@shiftapi/client` is added so TypeScript resolves the generated types.
+- **HMR** -- When `.go` files change, the plugin restarts the Go server, regenerates types, and triggers a full reload in the browser.
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,22 @@
+import { Plugin } from 'vite';
+
+interface ShiftAPIPluginOptions {
+    /** Path to the Go server entry point (e.g., "./cmd/server" or "./cmd/server/main.go") */
+    server: string;
+    /**
+     * Fallback base URL for the API client (default: "/").
+     * Can be overridden at build time via the `VITE_SHIFTAPI_BASE_URL` env var.
+     */
+    baseUrl?: string;
+    /** Working directory for `go run` (default: process.cwd()) */
+    goRoot?: string;
+    /**
+     * Address the Go server listens on (default: "http://localhost:8080").
+     * Used to auto-configure the Vite proxy in dev mode.
+     */
+    url?: string;
+}
+
+declare function shiftapiPlugin(options: ShiftAPIPluginOptions): Plugin;
+
+export { type ShiftAPIPluginOptions, shiftapiPlugin as default };

package/dist/index.js

@@ -0,0 +1,239 @@
+// src/index.ts
+import { resolve, relative } from "path";
+import {
+  writeFileSync,
+  readFileSync as readFileSync2,
+  mkdirSync,
+  existsSync
+} from "fs";
+import { spawn } from "child_process";
+
+// src/extract.ts
+import { execFileSync } from "child_process";
+import { readFileSync, unlinkSync, rmSync, mkdtempSync } from "fs";
+import { join } from "path";
+import { tmpdir } from "os";
+function extractSpec(serverEntry, goRoot) {
+  const tempDir = mkdtempSync(join(tmpdir(), "shiftapi-"));
+  const specPath = join(tempDir, "openapi.json");
+  try {
+    execFileSync("go", ["run", serverEntry], {
+      cwd: goRoot,
+      env: {
+        ...process.env,
+        SHIFTAPI_EXPORT_SPEC: specPath
+      },
+      stdio: ["ignore", "pipe", "pipe"],
+      timeout: 3e4
+    });
+  } catch (err) {
+    const stderr = err instanceof Error && "stderr" in err ? String(err.stderr) : "";
+    throw new Error(
+      `@shiftapi/vite-plugin: Failed to extract OpenAPI spec.
+  Command: go run ${serverEntry}
+  CWD: ${goRoot}
+  Error: ${stderr || String(err)}`
+    );
+  }
+  let raw;
+  try {
+    raw = readFileSync(specPath, "utf-8");
+  } catch {
+    throw new Error(
+      `@shiftapi/vite-plugin: Spec file was not created at ${specPath}.
+  Make sure your Go server calls shiftapi.ListenAndServe().`
+    );
+  }
+  try {
+    unlinkSync(specPath);
+    rmSync(tempDir, { recursive: true });
+  } catch {
+  }
+  return JSON.parse(raw);
+}
+
+// src/generate.ts
+import openapiTS, { astToString } from "openapi-typescript";
+async function generateTypes(spec) {
+  const ast = await openapiTS(spec);
+  return astToString(ast);
+}
+
+// src/virtualModule.ts
+function buildVirtualModuleSource(baseUrl) {
+  return `// Auto-generated by @shiftapi/vite-plugin
+import createClient from "openapi-fetch";
+
+/** Pre-configured, fully-typed API client. */
+export const client = createClient({
+  baseUrl: import.meta.env.VITE_SHIFTAPI_BASE_URL || ${JSON.stringify(baseUrl)},
+});
+
+export { createClient };
+`;
+}
+
+// src/index.ts
+var MODULE_ID = "@shiftapi/client";
+var RESOLVED_MODULE_ID = "\0" + MODULE_ID;
+function shiftapiPlugin(options) {
+  const {
+    server: serverEntry,
+    baseUrl = "/",
+    goRoot = process.cwd(),
+    url = "http://localhost:8080"
+  } = options;
+  let virtualModuleSource = "";
+  let generatedDts = "";
+  let cachedSpec = null;
+  let devServer;
+  let goProcess = null;
+  let debounceTimer = null;
+  let projectRoot = process.cwd();
+  function getSpec() {
+    if (!cachedSpec) {
+      cachedSpec = extractSpec(
+        serverEntry,
+        resolve(goRoot)
+      );
+    }
+    return cachedSpec;
+  }
+  async function regenerate() {
+    cachedSpec = null;
+    const spec = getSpec();
+    const types = await generateTypes(spec);
+    if (types === generatedDts) {
+      return false;
+    }
+    generatedDts = types;
+    virtualModuleSource = buildVirtualModuleSource(baseUrl);
+    return true;
+  }
+  function writeDtsFile() {
+    const outDir = resolve("node_modules", ".shiftapi");
+    if (!existsSync(outDir)) {
+      mkdirSync(outDir, { recursive: true });
+    }
+    const dtsContent = `// Auto-generated by @shiftapi/vite-plugin. Do not edit.
+declare module "@shiftapi/client" {
+${generatedDts.split("\n").map((line) => line ? "  " + line : line).join("\n")}
+
+  import type createClient from "openapi-fetch";
+
+  export const client: ReturnType<typeof createClient<paths>>;
+  export { createClient };
+}
+`;
+    writeFileSync(resolve(outDir, "client.d.ts"), dtsContent);
+  }
+  function patchTsConfig() {
+    const tsconfigPath = resolve(projectRoot, "tsconfig.json");
+    if (!existsSync(tsconfigPath)) return;
+    const raw = readFileSync2(tsconfigPath, "utf-8");
+    const tsconfig = JSON.parse(raw);
+    if (tsconfig?.compilerOptions?.paths?.[MODULE_ID]) return;
+    if (!tsconfig.compilerOptions) tsconfig.compilerOptions = {};
+    if (!tsconfig.compilerOptions.paths) tsconfig.compilerOptions.paths = {};
+    tsconfig.compilerOptions.paths[MODULE_ID] = [
+      "./node_modules/.shiftapi/client.d.ts"
+    ];
+    const indent = raw.match(/^[ \t]+/m)?.[0] ?? "  ";
+    writeFileSync(tsconfigPath, JSON.stringify(tsconfig, null, indent) + "\n");
+    console.log(
+      "[shiftapi] Updated tsconfig.json with @shiftapi/client path mapping"
+    );
+  }
+  function startGoServer() {
+    goProcess = spawn("go", ["run", serverEntry], {
+      cwd: resolve(goRoot),
+      stdio: ["ignore", "inherit", "inherit"]
+    });
+    goProcess.on("error", (err) => {
+      console.error("[shiftapi] Failed to start Go server:", err.message);
+    });
+    goProcess.on("exit", (code) => {
+      if (code !== null && code !== 0) {
+        console.error(`[shiftapi] Go server exited with code ${code}`);
+      }
+      goProcess = null;
+    });
+    console.log(`[shiftapi] Go server starting: go run ${serverEntry}`);
+  }
+  function stopGoServer() {
+    if (goProcess) {
+      goProcess.kill();
+      goProcess = null;
+    }
+  }
+  return {
+    name: "@shiftapi/vite-plugin",
+    configResolved(config) {
+      projectRoot = config.root;
+      patchTsConfig();
+    },
+    config() {
+      const spec = getSpec();
+      const paths = spec.paths;
+      if (!paths) return;
+      const proxy = {};
+      for (const path of Object.keys(paths)) {
+        proxy[path] = url;
+      }
+      return {
+        server: { proxy }
+      };
+    },
+    configureServer(server) {
+      devServer = server;
+      server.watcher.add(resolve(goRoot));
+      startGoServer();
+      server.httpServer?.on("close", stopGoServer);
+    },
+    async buildStart() {
+      await regenerate();
+      writeDtsFile();
+    },
+    resolveId(id) {
+      if (id === MODULE_ID) {
+        return RESOLVED_MODULE_ID;
+      }
+    },
+    load(id) {
+      if (id === RESOLVED_MODULE_ID) {
+        return virtualModuleSource;
+      }
+    },
+    async handleHotUpdate({ file }) {
+      const resolvedGoRoot = resolve(goRoot);
+      if (!file.endsWith(".go") || !file.startsWith(resolvedGoRoot)) {
+        return;
+      }
+      console.log(
+        `[shiftapi] Go file changed: ${relative(resolvedGoRoot, file)}`
+      );
+      if (debounceTimer) clearTimeout(debounceTimer);
+      debounceTimer = setTimeout(async () => {
+        try {
+          stopGoServer();
+          startGoServer();
+          const changed = await regenerate();
+          if (changed && devServer) {
+            writeDtsFile();
+            const mod = devServer.moduleGraph.getModuleById(RESOLVED_MODULE_ID);
+            if (mod) {
+              devServer.moduleGraph.invalidateModule(mod);
+              devServer.ws.send({ type: "full-reload" });
+            }
+            console.log("[shiftapi] Types regenerated.");
+          }
+        } catch (err) {
+          console.error("[shiftapi] Failed to regenerate:", err);
+        }
+      }, 500);
+    }
+  };
+}
+export {
+  shiftapiPlugin as default
+};

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@shiftapi/vite-plugin",
+  "version": "0.0.1",
+  "description": "Vite plugin for fully-typed TypeScript clients from shiftapi Go servers",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./virtual": {
+      "types": "./virtual.d.ts"
+    }
+  },
+  "files": [
+    "dist",
+    "virtual.d.ts"
+  ],
+  "scripts": {
+    "build": "tsup src/index.ts --format esm --dts",
+    "dev": "tsup src/index.ts --format esm --dts --watch",
+    "test": "vitest run"
+  },
+  "peerDependencies": {
+    "vite": "^5.0.0 || ^6.0.0"
+  },
+  "dependencies": {
+    "openapi-fetch": "^0.12.0 || ^0.13.0",
+    "openapi-typescript": "^7.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^25.2.3",
+    "openapi-fetch": "^0.13.0",
+    "tsup": "^8.0.0",
+    "typescript": "^5.5.0",
+    "vite": "^6.0.0",
+    "vitest": "^2.0.0"
+  }
+}

package/virtual.d.ts

@@ -0,0 +1,16 @@
+// Fallback type declaration for the @shiftapi/client virtual module.
+// Run `vite dev` or `vite build` to generate the real API-specific types.
+declare module "@shiftapi/client" {
+  import type createClient from "openapi-fetch";
+
+  /** OpenAPI paths type — generated from your Go API */
+  export type paths = Record<string, any>;
+  /** OpenAPI components type — generated from your Go API */
+  export type components = Record<string, any>;
+  /** OpenAPI operations type — generated from your Go API */
+  export type operations = Record<string, any>;
+
+  /** Pre-configured, fully-typed API client */
+  export const client: ReturnType<typeof createClient<paths>>;
+  export { createClient };
+}