@toapi/vite-plugin 0.3.0

package/README.md

@@ -0,0 +1,209 @@
+# @toapi/vite-plugin
+
+Vite plugin for [Toapi](https://github.com/farbenmeer/tapi). Bundles your Toapi
+API alongside your Vite frontend in a single project: serves the API as
+middleware in dev and preview mode, and produces a deployable server bundle
+for production.
+
+## Installation
+
+```bash
+pnpm add -D @toapi/vite-plugin
+pnpm add @toapi/server srvx
+```
+
+Peer-deps: `vite ^8`, `@toapi/server`.
+
+## Usage
+
+`vite.config.ts`:
+```ts
+import { defineConfig } from "vite";
+import toapi from "@toapi/vite-plugin";
+
+export default defineConfig({
+  plugins: [toapi()],
+});
+```
+
+The plugin expects `src/api.ts` to export `api` (an `ApiDefinition`):
+```ts
+import { defineApi, defineHandler, TResponse } from "@toapi/server";
+
+export const api = defineApi().route("/hello", {
+  GET: defineHandler({ authorize: () => true }, async () => {
+    return TResponse.json({ message: "hello" });
+  }),
+});
+```
+
+In dev (`vite`) and preview (`vite preview`) modes, the plugin attaches a
+middleware to Vite's server that handles requests at the configured
+`basePath` (default `/api`). The same Vite server serves both the frontend
+and the API on a single port.
+
+## Options
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `entry` | `string` | `"src/api.ts"` | Path to the file exporting `api`. Resolved against the Vite root. |
+| `basePath` | `string` | `"/api"` | Prefix for API routes. Use `""` to mount at the root. |
+| `port` | `number` | — | Default port for Vite's dev/preview server. Falls back to the `PORT` env var. |
+| `external` | `(string \| RegExp)[]` | `[]` | Packages to keep external in the server bundle. By default everything is bundled. |
+
+## Environment variables
+
+### Dev (`pnpm dev`)
+
+The plugin loads `.env`, `.env.local`, `.env.<mode>`, and `.env.<mode>.local`
+via Vite's `loadEnv` and mirrors every key into `process.env` before the api
+module is loaded. Existing `process.env` values keep precedence, so shell
+vars override `.env` files.
+
+```
+.env                     # all envs
+.env.local               # all envs, ignored by git
+.env.development         # dev only
+.env.development.local   # dev only, ignored by git
+```
+
+This covers server-side libraries that read `process.env.X` directly
+(BetterAuth, DB clients, OAuth secrets). Vite's `import.meta.env` injection
+still applies to client code.
+
+### Production (`srvx dist/server/server.js`)
+
+The built server does **not** load `.env` files. In production, env vars come
+from the runtime — Docker, systemd, or your PaaS. 
+
+
+## Build output
+
+`vite build` writes two clearly separated trees:
+
+```
+dist/
+├── client/        — static frontend assets (HTML, JS, CSS, images)
+├── server.js      — bundled server (sourcemap included)
+└── server.js.map
+```
+
+The split exists for safety: server-only code (database credentials,
+third-party API keys, server-side libraries) lives in `dist/server.js` and
+**must not** be deployed to a public static host. Treating `dist/client/` as
+the static-deploy root makes it impossible to leak the server bundle by
+accident.
+
+## Service worker
+
+To get tapi's offline / tag-based revalidation behavior, add a service
+worker built by [`vite-plugin-pwa`](https://vite-pwa-org.netlify.app/) in
+`injectManifest` mode. The two plugins compose cleanly: `tapi()` redirects
+the client build to `dist/client/`, which is exactly where VitePWA emits
+`sw.js`, and the production server bundle is built separately so
+nothing leaks across.
+
+```bash
+pnpm add -D vite-plugin-pwa
+```
+
+```ts
+// vite.config.ts
+import { defineConfig } from "vite";
+import tapi from "@toapi/vite-plugin";
+import { VitePWA } from "vite-plugin-pwa";
+
+export default defineConfig({
+  plugins: [
+    tapi(),
+    VitePWA({
+      strategies: "injectManifest",
+      srcDir: "src",
+      filename: "service-worker.ts",
+      injectRegister: "auto",
+      devOptions: { enabled: true, type: "module" },
+      // optional, pass-through to VitePWA:
+      // manifest: { name: "My App", short_name: "App", ... },
+    }),
+  ],
+});
+```
+
+```ts
+// src/service-worker.ts
+import {
+  handleTapiRequest,
+  listenForInvalidations,
+  cleanup,
+} from "@toapi/worker";
+
+declare const self: ServiceWorkerGlobalScope;
+
+self.addEventListener("activate", (event) => {
+  // Drop cache entries that have been expired longer than 7 days,
+  // remove orphans, and rebuild the tags index.
+  event.waitUntil(cleanup({ maximumStaleAge: 60 * 60 * 24 * 7 }));
+});
+
+self.addEventListener("fetch", (event) => {
+  const url = new URL(event.request.url);
+  if (
+    url.pathname.startsWith("/api") &&
+    !url.pathname.startsWith("/api/__tapi")
+  ) {
+    event.respondWith(handleTapiRequest(event.request));
+  }
+});
+
+listenForInvalidations({ url: "/api/__tapi/invalidations" });
+```
+
+Notes:
+
+- Add `"WebWorker"` to your `tsconfig.json` `lib` array so TypeScript
+  recognizes `ServiceWorkerGlobalScope` and friends.
+- `devOptions.enabled: true` makes the SW run during `vite dev` too;
+  otherwise it only runs in `vite preview` and production.
+- Adjust the `/api` checks in the SW to match the `basePath` you pass to
+  `tapi()`.
+- `cleanup`'s `maximumStaleAge` is the grace period (in seconds) past a
+  cache entry's `expiresAt` before it's actually deleted on next SW
+  activation.
+
+## Deployment
+
+The server bundle is a fetch-handler module. Serve it in production with the
+[srvx](https://srvx.h3.dev) CLI:
+
+```bash
+srvx --prod dist/server.js
+```
+
+`srvx` picks up `PORT`, `HOST`, and other settings from environment variables.
+
+### Static assets
+
+Static frontend assets in `dist/client/` should ideally be served by a
+dedicated static host — nginx, Caddy, or an S3-compatible bucket fronted by a
+CDN. Dedicated static hosts give you better caching, compression, HTTP/2,
+and offload the load from your Node.js server.
+
+If you don't want a separate static host, srvx can serve them too with the
+`-s` flag:
+
+```bash
+srvx --prod -s client dist/server.js
+```
+
+The path passed to `-s` is resolved **relative to the directory containing
+the entry file** (`dist/`), so `client` points at `dist/client/`.
+API routes are matched first; static files fall through when no API route
+handles the request.
+
+> **Note:** `srvx -s` serves files as-is. It has **no SPA history fallback**
+> (deep-linking or reloading a client-side route returns `404`) and sets **no
+> `Cache-Control`/`ETag`** — content-hashed assets are not marked `immutable`
+> and there is no `304` revalidation. For a client-routed SPA in production,
+> front it with a static server or CDN that handles the history fallback and
+> caching. See the reference `Caddyfile` in
+> [`examples/vite-plugin-tapi-demo`](https://github.com/farbenmeer/tapi/tree/main/examples/vite-plugin-tapi-demo).

package/dist/ApiHandler.d.ts

@@ -0,0 +1,2 @@
+export type ApiHandler = (request: Request) => Promise<Response> | Response;
+//# sourceMappingURL=ApiHandler.d.ts.map

package/dist/ApiHandler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ApiHandler.d.ts","sourceRoot":"","sources":["../src/ApiHandler.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,UAAU,GAAG,CAAC,OAAO,EAAE,OAAO,KAAK,OAAO,CAAC,QAAQ,CAAC,GAAG,QAAQ,CAAC"}

package/dist/createApiMiddleware.d.ts

@@ -0,0 +1,4 @@
+import type { Connect } from "vite";
+import type { ApiHandler } from "./ApiHandler.js";
+export declare function createApiMiddleware(getHandler: () => ApiHandler | undefined, basePath: string): Connect.NextHandleFunction;
+//# sourceMappingURL=createApiMiddleware.d.ts.map

package/dist/createApiMiddleware.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"createApiMiddleware.d.ts","sourceRoot":"","sources":["../src/createApiMiddleware.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,MAAM,CAAC;AAEpC,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAElD,wBAAgB,mBAAmB,CACjC,UAAU,EAAE,MAAM,UAAU,GAAG,SAAS,EACxC,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,kBAAkB,CAsB5B"}

package/dist/createApiMiddleware.js

@@ -0,0 +1,24 @@
+import { NodeRequest, sendNodeResponse } from "srvx/node";
+export function createApiMiddleware(getHandler, basePath) {
+    return async (req, res, next) => {
+        try {
+            const handler = getHandler();
+            if (!handler)
+                return next();
+            const url = req.url ?? "/";
+            if (basePath && !url.startsWith(basePath))
+                return next();
+            const webReq = new NodeRequest({ req, res });
+            const webRes = await handler(webReq);
+            // When there's no basePath restriction, fall through to Vite on 404
+            // so static files, HMR, etc. are still served correctly.
+            if (webRes.status === 404 && !basePath)
+                return next();
+            await sendNodeResponse(res, webRes);
+        }
+        catch (error) {
+            console.error(`[vite-plugin-tapi]`, error);
+            next();
+        }
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1,25 @@
+import type { Plugin } from "vite";
+export interface TapiPluginOptions {
+    /**
+     * Path to the file that exports `api` (a TApi `ApiDefinition`).
+     * Resolved against the Vite root. Default: `"src/api.ts"`.
+     */
+    entry?: string;
+    /**
+     * Base path passed to `createRequestHandler`. Default: `"/api"`.
+     */
+    basePath?: string;
+    /**
+     * Default port for Vite's dev/preview server. Falls back to the `PORT`
+     * environment variable when set.
+     */
+    port?: number;
+    /**
+     * Packages to keep external in the server bundle.
+     * Passed directly to `rolldownOptions.external`.
+     * Default: `[]` — everything is bundled.
+     */
+    external?: (string | RegExp)[];
+}
+export default function tapi(options?: TapiPluginOptions): Plugin;
+//# 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":"AAEA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,MAAM,CAAC;AAKnC,MAAM,WAAW,iBAAiB;IAChC;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;OAEG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;OAGG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;;;OAIG;IACH,QAAQ,CAAC,EAAE,CAAC,MAAM,GAAG,MAAM,CAAC,EAAE,CAAC;CAChC;AAED,MAAM,CAAC,OAAO,UAAU,IAAI,CAAC,OAAO,GAAE,iBAAsB,GAAG,MAAM,CA4LpE"}

package/dist/index.js

@@ -0,0 +1,163 @@
+import { createRequestHandler } from "@toapi/server";
+import path from "node:path";
+import { loadEnv } from "vite";
+import { createApiMiddleware } from "./createApiMiddleware.js";
+export default function tapi(options = {}) {
+    const entryOption = options.entry ?? "src/api.ts";
+    const basePath = options.basePath ?? "/api";
+    let userOutDirBase = "dist";
+    let resolvedEntry = "";
+    let resolvedRoot = "";
+    let serverOutDir = "";
+    let isBuildCommand = false;
+    let currentHandler;
+    return {
+        name: "vite-plugin-tapi",
+        config(userConfig, _env) {
+            // Capture the user's outDir BEFORE we override it, so we can compute
+            // the parallel server output directory in later hooks.
+            userOutDirBase = userConfig.build?.outDir ?? "dist";
+            const port = options.port ??
+                (process.env.PORT ? Number(process.env.PORT) : undefined);
+            // Always redirect the client build to <outDir>/client so server code
+            // (written by closeBundle into <outDir>/server) cannot leak into the
+            // static hosting deploy.
+            return {
+                build: { outDir: path.join(userOutDirBase, "client") },
+                ...(port ? { server: { port }, preview: { port } } : {}),
+            };
+        },
+        configResolved(config) {
+            resolvedEntry = path.isAbsolute(entryOption)
+                ? entryOption
+                : path.resolve(config.root, entryOption);
+            resolvedRoot = config.root;
+            serverOutDir = path.resolve(config.root, userOutDirBase);
+            isBuildCommand = config.command === "build";
+        },
+        async configureServer(vite) {
+            // Vite injects .env values into `import.meta.env` for the client only;
+            // the api runs in this same Node process and reads `process.env`. Mirror
+            // every var (empty prefix, not just VITE_*) into process.env so server
+            // code sees secrets like BETTER_AUTH_SECRET. Existing process.env wins.
+            const env = loadEnv(vite.config.mode, vite.config.envDir, "");
+            for (const [k, v] of Object.entries(env)) {
+                if (process.env[k] === undefined)
+                    process.env[k] = v;
+            }
+            const loadHandler = async () => {
+                const mod = (await vite.ssrLoadModule(resolvedEntry));
+                if (!mod.api) {
+                    throw new Error(`[vite-plugin-tapi] ${resolvedEntry} must export \`api\` (an ApiDefinition).`);
+                }
+                if (!mod.api.logger) {
+                    mod.api.logger = {
+                        error: (error) => {
+                            if (error instanceof Error)
+                                vite.ssrFixStacktrace(error);
+                            console.error(error);
+                        },
+                    };
+                }
+                currentHandler = createRequestHandler(mod.api, {
+                    basePath,
+                });
+            };
+            try {
+                await loadHandler();
+            }
+            catch (err) {
+                if (err instanceof Error)
+                    vite.ssrFixStacktrace(err);
+                console.error("[vite-plugin-tapi] initial load failed:", err);
+            }
+            vite.middlewares.use(createApiMiddleware(() => currentHandler, basePath));
+            const onChange = async () => {
+                vite.moduleGraph.invalidateAll();
+                try {
+                    await loadHandler();
+                }
+                catch (err) {
+                    if (err instanceof Error)
+                        vite.ssrFixStacktrace(err);
+                    console.error("[vite-plugin-tapi] reload failed:", err);
+                }
+            };
+            vite.watcher.on("change", onChange);
+            vite.watcher.on("add", onChange);
+            vite.watcher.on("unlink", onChange);
+        },
+        async configurePreviewServer(previewServer) {
+            // Same rationale as configureServer: mirror .env values into process.env
+            // so the bundled server (running in this same Node process) can read
+            // secrets via process.env. Existing process.env wins.
+            const env = loadEnv(previewServer.config.mode, previewServer.config.envDir, "");
+            for (const [k, v] of Object.entries(env)) {
+                if (process.env[k] === undefined)
+                    process.env[k] = v;
+            }
+            const serverJsPath = path.join(path.resolve(previewServer.config.root, userOutDirBase), "server.js");
+            let fetchHandler;
+            try {
+                const mod = (await import(serverJsPath));
+                fetchHandler = mod.default?.fetch ?? mod.fetch;
+                if (!fetchHandler) {
+                    console.warn("[vite-plugin-tapi] dist/server/server.js has no fetch export — run `vite build` first.");
+                }
+            }
+            catch (err) {
+                console.error("[vite-plugin-tapi] failed to import dist/server/server.js for preview:", err);
+            }
+            if (!fetchHandler)
+                return;
+            previewServer.middlewares.use(createApiMiddleware(() => fetchHandler, basePath));
+        },
+        async closeBundle() {
+            if (!isBuildCommand)
+                return;
+            const VIRTUAL_SERVER_ID = "virtual:tapi-server";
+            const RESOLVED_VIRTUAL_SERVER_ID = "\0" + VIRTUAL_SERVER_ID;
+            const inlinePlugin = () => ({
+                name: "tapi-server-virtual",
+                resolveId(id) {
+                    return id === VIRTUAL_SERVER_ID ? RESOLVED_VIRTUAL_SERVER_ID : null;
+                },
+                load(id) {
+                    if (id !== RESOLVED_VIRTUAL_SERVER_ID)
+                        return null;
+                    return [
+                        `import { createRequestHandler } from "@toapi/server";`,
+                        `import { api } from ${JSON.stringify(resolvedEntry)};`,
+                        ``,
+                        `export const fetch = createRequestHandler(api, { basePath: ${JSON.stringify(basePath)} });`,
+                        `export default { fetch };`,
+                    ].join("\n");
+                },
+            });
+            const { build } = await import("vite");
+            await build({
+                root: resolvedRoot,
+                configFile: false,
+                logLevel: "silent",
+                plugins: [inlinePlugin()],
+                // noExternal: true so node_modules are bundled by default;
+                // only packages in options.external are kept external.
+                ssr: { noExternal: true },
+                build: {
+                    ssr: true,
+                    outDir: serverOutDir,
+                    emptyOutDir: false,
+                    sourcemap: true,
+                    rolldownOptions: {
+                        input: { server: VIRTUAL_SERVER_ID },
+                        output: {
+                            format: "esm",
+                            entryFileNames: "[name].js",
+                        },
+                        external: options.external ?? [],
+                    },
+                },
+            });
+        },
+    };
+}

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@toapi/vite-plugin",
+  "version": "0.3.0",
+  "author": {
+    "name": "Michel Smola",
+    "email": "michel.smola@farbenmeer.de"
+  },
+  "type": "module",
+  "module": "dist/index.js",
+  "main": "dist/index.js",
+  "private": false,
+  "license": "MIT",
+  "files": [
+    "dist"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "dependencies": {
+    "srvx": "^0.11.15"
+  },
+  "peerDependencies": {
+    "typescript": "^5 || ^6.0.0",
+    "vite": "^8.0.0",
+    "@toapi/server": "^0.12.1"
+  },
+  "devDependencies": {
+    "@types/node": "^25.0.3",
+    "vite": "^8.0.9",
+    "@toapi/server": "^0.12.1"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/farbenmeer/tapi.git"
+  },
+  "scripts": {
+    "build": "tsc --noEmit false",
+    "release": "pnpm build && pnpm publish --no-git-checks"
+  }
+}