@donkeylabs/adapter-sveltekit 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 DonkeyLabs
+
+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,181 @@
+# @donkeylabs/adapter-sveltekit
+
+SvelteKit adapter for `@donkeylabs/server`. Enables seamless integration between SvelteKit and your backend API with:
+
+- **Single Bun process** serves both SvelteKit pages and API routes
+- **Direct service calls during SSR** (no HTTP overhead)
+- **Unified API client** works identically in SSR and browser
+
+## Installation
+
+```bash
+bun add @donkeylabs/adapter-sveltekit
+```
+
+## Quick Start
+
+### 1. Configure the Adapter
+
+```ts
+// svelte.config.js
+import adapter from "@donkeylabs/adapter-sveltekit";
+
+export default {
+  kit: {
+    adapter: adapter({
+      serverEntry: "./src/server/index.ts",
+    }),
+  },
+};
+```
+
+### 2. Add Vite Plugin for Development
+
+```ts
+// vite.config.ts
+import { sveltekit } from "@sveltejs/kit/vite";
+import { donkeylabsDev } from "@donkeylabs/adapter-sveltekit/vite";
+import { defineConfig } from "vite";
+
+export default defineConfig({
+  plugins: [
+    donkeylabsDev({ serverEntry: "./src/server/index.ts" }),
+    sveltekit(),
+  ],
+});
+```
+
+### 3. Set Up Server Hooks
+
+```ts
+// src/hooks.server.ts
+import { createHandle } from "@donkeylabs/adapter-sveltekit/hooks";
+
+export const handle = createHandle();
+```
+
+### 4. Generate API Client
+
+```ts
+// donkeylabs.config.ts
+import { defineConfig } from "@donkeylabs/server";
+import { SvelteKitClientGenerator } from "@donkeylabs/adapter-sveltekit/generator";
+
+export default defineConfig({
+  plugins: ["./src/server/plugins/**/index.ts"],
+  client: {
+    output: "./src/lib/api.ts",
+    generator: SvelteKitClientGenerator,
+  },
+});
+```
+
+### 5. Use the API Client
+
+```svelte
+<!-- src/routes/+page.svelte -->
+<script lang="ts">
+  import { ApiClient } from "$lib/api";
+
+  const api = new ApiClient();
+
+  async function greet() {
+    const result = await api.greet({ name: "World" });
+    console.log(result.message);
+  }
+</script>
+```
+
+In SSR (`+page.server.ts`), pass `locals` for direct service calls:
+
+```ts
+// src/routes/+page.server.ts
+import { ApiClient } from "$lib/api";
+
+export async function load({ locals, fetch }) {
+  const api = new ApiClient({ locals, fetch });
+  const data = await api.getData({}); // Direct call, no HTTP!
+  return { data };
+}
+```
+
+## Development Modes
+
+### Recommended: In-Process Mode
+
+Run with `bun --bun` for single-process development:
+
+```bash
+bun --bun run dev
+```
+
+- Single port (5173)
+- Direct service calls during SSR
+- Hot reload for both frontend and backend
+
+### Fallback: Subprocess Mode
+
+Run without `--bun` flag:
+
+```bash
+bun run dev
+```
+
+- Two processes (Vite on 5173, backend on 3001)
+- API requests proxied to backend
+- Use when in-process mode has compatibility issues
+
+## Production Build
+
+```bash
+bun run build
+bun build/server/entry.js
+```
+
+## Package Exports
+
+| Export | Description |
+|--------|-------------|
+| `@donkeylabs/adapter-sveltekit` | Main adapter function |
+| `@donkeylabs/adapter-sveltekit/client` | Unified API client base |
+| `@donkeylabs/adapter-sveltekit/hooks` | SvelteKit hooks helpers |
+| `@donkeylabs/adapter-sveltekit/generator` | Client code generator |
+| `@donkeylabs/adapter-sveltekit/vite` | Vite dev plugin |
+
+## Type Definitions
+
+Add to your `app.d.ts`:
+
+```ts
+// src/app.d.ts
+import type { DonkeylabsLocals } from "@donkeylabs/adapter-sveltekit/hooks";
+
+declare global {
+  namespace App {
+    interface Locals extends DonkeylabsLocals {}
+  }
+}
+
+export {};
+```
+
+## SSE (Server-Sent Events)
+
+Subscribe to real-time events in the browser:
+
+```ts
+const api = new ApiClient();
+
+const unsubscribe = api.sse.subscribe(
+  ["notifications", "updates"],
+  (event, data) => {
+    console.log("Event:", event, data);
+  }
+);
+
+// Later: unsubscribe();
+```
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "@donkeylabs/adapter-sveltekit",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "SvelteKit adapter for @donkeylabs/server - seamless SSR/browser API integration",
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "import": "./src/index.ts"
+    },
+    "./client": {
+      "types": "./src/client/index.ts",
+      "import": "./src/client/index.ts"
+    },
+    "./hooks": {
+      "types": "./src/hooks/index.ts",
+      "import": "./src/hooks/index.ts"
+    },
+    "./generator": {
+      "types": "./src/generator/index.ts",
+      "import": "./src/generator/index.ts"
+    },
+    "./vite": {
+      "types": "./src/vite.ts",
+      "import": "./src/vite.ts"
+    }
+  },
+  "files": [
+    "src",
+    "LICENSE",
+    "README.md"
+  ],
+  "scripts": {
+    "typecheck": "bun --bun tsc --noEmit"
+  },
+  "peerDependencies": {
+    "@sveltejs/kit": "^2.0.0",
+    "@donkeylabs/server": "*"
+  },
+  "keywords": [
+    "sveltekit",
+    "svelte",
+    "adapter",
+    "api",
+    "rpc",
+    "ssr",
+    "bun",
+    "typescript"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/donkeylabs/server",
+    "directory": "packages/adapter-sveltekit"
+  },
+  "license": "MIT"
+}

package/src/client/index.ts

@@ -0,0 +1,185 @@
+/**
+ * Unified API client for @donkeylabs/adapter-sveltekit
+ *
+ * Auto-detects environment:
+ * - SSR: Direct service calls through locals (no HTTP)
+ * - Browser: HTTP calls to API routes
+ */
+
+export interface RequestOptions {
+  headers?: Record<string, string>;
+  signal?: AbortSignal;
+}
+
+export interface ClientOptions {
+  /** Base URL for HTTP calls. Defaults to empty string (relative URLs). */
+  baseUrl?: string;
+  /** SvelteKit locals object for SSR direct calls. */
+  locals?: any;
+  /** Custom fetch function. In SSR, pass event.fetch to handle relative URLs. */
+  fetch?: typeof fetch;
+}
+
+export interface SSESubscription {
+  unsubscribe: () => void;
+}
+
+/**
+ * Base class for unified API clients.
+ * Extend this class with your generated route methods.
+ */
+export class UnifiedApiClientBase {
+  protected baseUrl: string;
+  protected locals?: any;
+  protected isSSR: boolean;
+  protected customFetch?: typeof fetch;
+
+  constructor(options?: ClientOptions) {
+    this.baseUrl = options?.baseUrl ?? "";
+    this.locals = options?.locals;
+    this.isSSR = typeof window === "undefined";
+    this.customFetch = options?.fetch;
+  }
+
+  /**
+   * Make a request to an API route.
+   * Automatically uses direct calls in SSR (when locals.handleRoute is available), HTTP otherwise.
+   */
+  protected async request<TInput, TOutput>(
+    route: string,
+    input: TInput,
+    options?: RequestOptions
+  ): Promise<TOutput> {
+    // Use direct route handler if available (SSR with locals)
+    if (this.locals?.handleRoute) {
+      return this.locals.handleRoute(route, input);
+    }
+    // Fall back to HTTP (browser or SSR without locals)
+    return this.httpCall<TInput, TOutput>(route, input, options);
+  }
+
+  /**
+   * HTTP call to API endpoint (browser or SSR with event.fetch).
+   */
+  private async httpCall<TInput, TOutput>(
+    route: string,
+    input: TInput,
+    options?: RequestOptions
+  ): Promise<TOutput> {
+    const url = `${this.baseUrl}/${route}`;
+    const fetchFn = this.customFetch ?? fetch;
+
+    const response = await fetchFn(url, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        ...options?.headers,
+      },
+      body: JSON.stringify(input),
+      signal: options?.signal,
+    });
+
+    if (!response.ok) {
+      const error = await response.json().catch(() => ({ error: "Unknown error" }));
+      throw new Error(error.message || error.error || `HTTP ${response.status}`);
+    }
+
+    return response.json();
+  }
+
+  /**
+   * SSE (Server-Sent Events) subscription.
+   * Only works in the browser.
+   */
+  sse = {
+    /**
+     * Subscribe to SSE channels.
+     * Returns a function to unsubscribe.
+     *
+     * @example
+     * const unsub = api.sse.subscribe(["notifications"], (event, data) => {
+     *   console.log(event, data);
+     * });
+     * // Later: unsub();
+     */
+    subscribe: (
+      channels: string[],
+      callback: (event: string, data: any) => void,
+      options?: { reconnect?: boolean }
+    ): (() => void) => {
+      if (typeof window === "undefined") {
+        // SSR - return no-op
+        return () => {};
+      }
+
+      const url = `${this.baseUrl}/sse?channels=${channels.join(",")}`;
+      let eventSource: EventSource | null = new EventSource(url);
+      let reconnectTimeout: ReturnType<typeof setTimeout> | null = null;
+
+      // Known event types from the server
+      const eventTypes = ['cron-event', 'job-completed', 'internal-event', 'manual', 'message'];
+
+      const handleMessage = (e: MessageEvent) => {
+        try {
+          const data = JSON.parse(e.data);
+          callback(e.type || "message", data);
+        } catch {
+          callback(e.type || "message", e.data);
+        }
+      };
+
+      const handleError = () => {
+        if (options?.reconnect !== false && eventSource) {
+          eventSource.close();
+          reconnectTimeout = setTimeout(() => {
+            eventSource = new EventSource(url);
+            // Re-attach all listeners on reconnect
+            eventSource.onmessage = handleMessage;
+            eventSource.onerror = handleError;
+            for (const type of eventTypes) {
+              eventSource.addEventListener(type, handleMessage);
+            }
+          }, 1000);
+        }
+      };
+
+      // Listen for unnamed messages
+      eventSource.onmessage = handleMessage;
+      eventSource.onerror = handleError;
+
+      // Listen for named event types (SSE sends "event: type-name")
+      for (const type of eventTypes) {
+        eventSource.addEventListener(type, handleMessage);
+      }
+
+      // Return unsubscribe function
+      return () => {
+        if (reconnectTimeout) {
+          clearTimeout(reconnectTimeout);
+        }
+        if (eventSource) {
+          eventSource.close();
+          eventSource = null;
+        }
+      };
+    },
+  };
+}
+
+/**
+ * Create an API client instance.
+ * Call with locals and fetch in SSR, without in browser.
+ *
+ * @example
+ * // +page.server.ts (SSR)
+ * const api = createApiClient({ locals, fetch });
+ *
+ * // +page.svelte (browser)
+ * const api = createApiClient();
+ */
+export function createApiClient<T extends UnifiedApiClientBase>(
+  ClientClass: new (options?: ClientOptions) => T,
+  options?: ClientOptions
+): T {
+  return new ClientClass(options);
+}

package/src/generator/index.ts

@@ -0,0 +1,80 @@
+/**
+ * SvelteKit-specific client generator
+ *
+ * This generator extends the core @donkeylabs/server generator
+ * to produce clients that work with both SSR (direct calls) and browser (HTTP).
+ */
+
+import { mkdir, writeFile } from "node:fs/promises";
+import { dirname } from "node:path";
+import {
+  generateClientFromRoutes,
+  type ExtractedRoute,
+  type ClientGeneratorOptions,
+} from "@donkeylabs/server/generator";
+
+/** SvelteKit-specific generator options */
+export const svelteKitGeneratorOptions: ClientGeneratorOptions = {
+  baseImport:
+    'import { UnifiedApiClientBase, type ApiClientOptions } from "@donkeylabs/adapter-sveltekit/client";',
+  baseClass: "UnifiedApiClientBase",
+  constructorSignature: "options?: ApiClientOptions",
+  constructorBody: "super(options);",
+  factoryFunction: `/**
+ * Create an API client instance
+ *
+ * @param options.locals - Pass SvelteKit locals for SSR direct calls (no HTTP overhead)
+ * @param options.baseUrl - Override the base URL for HTTP calls
+ *
+ * @example SSR usage in +page.server.ts:
+ * \`\`\`ts
+ * export const load = async ({ locals }) => {
+ *   const api = createApi({ locals });
+ *   const data = await api.myRoute.get({}); // Direct call, no HTTP!
+ *   return { data };
+ * };
+ * \`\`\`
+ *
+ * @example Browser usage in +page.svelte:
+ * \`\`\`svelte
+ * <script>
+ *   import { createApi } from '$lib/api';
+ *   const api = createApi(); // HTTP calls
+ *   let data = $state(null);
+ *   async function load() {
+ *     data = await api.myRoute.get({});
+ *   }
+ * </script>
+ * \`\`\`
+ */
+export function createApi(options?: ApiClientOptions) {
+  return new ApiClient(options);
+}`,
+};
+
+/**
+ * Generate a SvelteKit-compatible API client
+ *
+ * This is called by the donkeylabs CLI when adapter is set to "@donkeylabs/adapter-sveltekit"
+ */
+export async function generateClient(
+  _config: Record<string, unknown>,
+  routes: ExtractedRoute[],
+  outputPath: string
+): Promise<void> {
+  const code = generateClientFromRoutes(routes, svelteKitGeneratorOptions);
+
+  // Ensure output directory exists
+  const outputDir = dirname(outputPath);
+  await mkdir(outputDir, { recursive: true });
+
+  // Write the generated client
+  await writeFile(outputPath, code);
+}
+
+// Re-export building blocks for advanced usage
+export {
+  generateClientFromRoutes,
+  type ExtractedRoute,
+  type ClientGeneratorOptions,
+} from "@donkeylabs/server/generator";

package/src/hooks/index.ts

@@ -0,0 +1,124 @@
+/**
+ * SvelteKit hooks helper for @donkeylabs/adapter-sveltekit
+ */
+
+import type { Handle } from "@sveltejs/kit";
+
+// Try to import dev server reference (only available in dev mode)
+let getDevServer: (() => any) | undefined;
+try {
+  // Dynamic import to avoid bundling vite.ts in production
+  const viteModule = await import("../vite.js");
+  getDevServer = viteModule.getDevServer;
+} catch {
+  // Not in dev mode or vite not available
+}
+
+export interface DonkeylabsPlatform {
+  donkeylabs?: {
+    services: Record<string, any>;
+    core: {
+      logger: any;
+      cache: any;
+      events: any;
+      cron: any;
+      jobs: any;
+      sse: any;
+      rateLimiter: any;
+      db: any;
+    };
+    /** Direct route handler for SSR (no HTTP!) */
+    handleRoute: (routeName: string, input: any) => Promise<any>;
+  };
+}
+
+export interface DonkeylabsLocals {
+  plugins: Record<string, any>;
+  core: {
+    logger: any;
+    cache: any;
+    events: any;
+    sse: any;
+  };
+  db: any;
+  ip: string;
+  /** Direct route handler for SSR API calls */
+  handleRoute?: (routeName: string, input: any) => Promise<any>;
+}
+
+/**
+ * Create a SvelteKit handle function that populates event.locals
+ * with @donkeylabs/server context.
+ *
+ * @example
+ * // src/hooks.server.ts
+ * import { createHandle } from "@donkeylabs/adapter-sveltekit/hooks";
+ * export const handle = createHandle();
+ */
+export function createHandle(): Handle {
+  return async ({ event, resolve }) => {
+    const platform = event.platform as DonkeylabsPlatform | undefined;
+
+    if (platform?.donkeylabs) {
+      // Production mode: use platform.donkeylabs from adapter
+      const { services, core, handleRoute } = platform.donkeylabs;
+
+      // Populate locals with server context
+      (event.locals as DonkeylabsLocals).plugins = services;
+      (event.locals as DonkeylabsLocals).core = {
+        logger: core.logger,
+        cache: core.cache,
+        events: core.events,
+        sse: core.sse,
+      };
+      (event.locals as DonkeylabsLocals).db = core.db;
+      (event.locals as DonkeylabsLocals).ip = event.getClientAddress();
+      // Expose the direct route handler for SSR API calls
+      (event.locals as DonkeylabsLocals).handleRoute = handleRoute;
+    } else if (getDevServer) {
+      // Dev mode: use global dev server from vite plugin
+      const devServer = getDevServer();
+      if (devServer) {
+        const core = devServer.getCore();
+        const plugins = devServer.getServices();
+
+        (event.locals as DonkeylabsLocals).plugins = plugins;
+        (event.locals as DonkeylabsLocals).core = {
+          logger: core.logger,
+          cache: core.cache,
+          events: core.events,
+          sse: core.sse,
+        };
+        (event.locals as DonkeylabsLocals).db = core.db;
+        (event.locals as DonkeylabsLocals).ip = event.getClientAddress();
+        // Direct route handler for SSR
+        (event.locals as DonkeylabsLocals).handleRoute = async (routeName: string, input: any) => {
+          return devServer.callRoute(routeName, input, event.getClientAddress());
+        };
+      }
+    }
+
+    return resolve(event);
+  };
+}
+
+/**
+ * Sequence multiple handle functions together.
+ *
+ * @example
+ * import { sequence, createHandle } from "@donkeylabs/adapter-sveltekit/hooks";
+ * export const handle = sequence(createHandle(), myOtherHandle);
+ */
+export function sequence(...handlers: Handle[]): Handle {
+  return async ({ event, resolve }) => {
+    let resolveChain = resolve;
+
+    for (let i = handlers.length - 1; i >= 0; i--) {
+      const handler = handlers[i];
+      const next = resolveChain;
+      resolveChain = (event) => handler({ event, resolve: next });
+    }
+
+    return resolveChain(event);
+  };
+}

package/src/index.ts

@@ -0,0 +1,395 @@
+/**
+ * @donkeylabs/adapter-sveltekit
+ *
+ * SvelteKit adapter that integrates with @donkeylabs/server.
+ * - Single Bun process serves both SvelteKit pages and API routes
+ * - Direct service calls during SSR (no HTTP overhead)
+ * - Unified API client works in both SSR and browser
+ */
+
+import type { Adapter, Builder } from "@sveltejs/kit";
+import { fileURLToPath } from "node:url";
+import { dirname, join, relative, resolve } from "node:path";
+import { writeFileSync, mkdirSync } from "node:fs";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+export interface AdapterOptions {
+  /**
+   * Output directory for the built app.
+   * @default "build"
+   */
+  out?: string;
+
+  /**
+   * Path to your @donkeylabs/server entry file.
+   * This file should export a configured AppServer instance.
+   *
+   * @example "./src/server/index.ts"
+   */
+  serverEntry: string;
+
+  /**
+   * Whether to precompress static assets with gzip/brotli.
+   * @default true
+   */
+  precompress?: boolean;
+
+  /**
+   * Environment variable prefix for PORT and HOST.
+   * @default ""
+   */
+  envPrefix?: string;
+
+  /**
+   * Enable development mode features.
+   * @default false
+   */
+  development?: boolean;
+}
+
+export default function adapter(options: AdapterOptions): Adapter {
+  const {
+    out = "build",
+    serverEntry,
+    precompress = true,
+    envPrefix = "",
+    development = false,
+  } = options;
+
+  if (!serverEntry) {
+    throw new Error("@donkeylabs/adapter-sveltekit: serverEntry option is required");
+  }
+
+  return {
+    name: "@donkeylabs/adapter-sveltekit",
+
+    async adapt(builder: Builder) {
+      const serverDir = join(out, "server");
+      const clientDir = join(out, "client");
+      const prerenderedDir = join(out, "prerendered");
+
+      // 1. Clean and create output directories
+      builder.rimraf(out);
+      mkdirSync(serverDir, { recursive: true });
+
+      builder.log.minor("Writing SvelteKit server files...");
+
+      // 2. Write SvelteKit server files
+      builder.writeServer(serverDir);
+
+      // 3. Copy static assets and prerendered pages
+      const clientFiles = builder.writeClient(clientDir);
+      const prerenderedFiles = builder.writePrerendered(prerenderedDir);
+
+      // 4. Generate the manifest
+      const relativePath = relative(serverDir, ".");
+      builder.generateManifest({ relativePath });
+
+      // 5. Generate the unified runtime entry point
+      const serverEntryResolved = resolve(serverEntry);
+      const serverEntryRelative = relative(serverDir, serverEntryResolved);
+
+      const entryCode = generateEntryPoint({
+        serverEntryRelative,
+        envPrefix,
+        development,
+        clientDir: relative(serverDir, clientDir),
+        prerenderedDir: relative(serverDir, prerenderedDir),
+      });
+
+      writeFileSync(join(serverDir, "entry.js"), entryCode);
+
+      // 6. Write runtime handler (inline the full implementation)
+      writeFileSync(join(serverDir, "handler.js"), generateRuntimeHandler());
+
+      // 7. Precompress if enabled
+      if (precompress) {
+        builder.log.minor("Compressing assets...");
+        await builder.compress(clientDir);
+        if (prerenderedFiles.length > 0) {
+          await builder.compress(prerenderedDir);
+        }
+      }
+
+      builder.log.success(`Adapter output written to ${out}`);
+      builder.log.minor(`Run with: bun ${out}/server/entry.js`);
+    },
+  };
+}
+
+function generateEntryPoint(config: {
+  serverEntryRelative: string;
+  envPrefix: string;
+  development: boolean;
+  clientDir: string;
+  prerenderedDir: string;
+}): string {
+  const { serverEntryRelative, envPrefix, development, clientDir, prerenderedDir } = config;
+
+  return `// Generated by @donkeylabs/adapter-sveltekit
+import { Server } from "./index.js";
+import { manifest } from "./manifest.js";
+import { createUnifiedServer } from "./handler.js";
+
+// Import user's @donkeylabs/server setup
+const serverModule = await import("${serverEntryRelative}");
+const donkeylabsServer = serverModule.server || serverModule.default;
+
+if (!donkeylabsServer) {
+  throw new Error(
+    "@donkeylabs/adapter-sveltekit: Could not find server export. " +
+    "Make sure your server entry file exports 'server' or uses default export."
+  );
+}
+
+// Initialize @donkeylabs/server (migrations, plugins, routes)
+await donkeylabsServer.initialize();
+
+// Create SvelteKit server
+const svelteServer = new Server(manifest);
+await svelteServer.init({ env: process.env });
+
+// Configuration
+const port = Number(process.env.${envPrefix}PORT) || 3000;
+const host = process.env.${envPrefix}HOST || "0.0.0.0";
+const development = ${development} || process.env.NODE_ENV === "development";
+
+// Start unified server
+createUnifiedServer({
+  svelteServer,
+  donkeylabsServer,
+  port,
+  host,
+  clientDir: "${clientDir}",
+  prerenderedDir: "${prerenderedDir}",
+  development,
+});
+
+console.log(\`Server running at http://\${host}:\${port}\`);
+`;
+}
+
+function generateRuntimeHandler(): string {
+  // Inline the full runtime handler implementation
+  return `// Generated runtime handler by @donkeylabs/adapter-sveltekit
+import { resolve, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+/**
+ * Create a unified Bun server that handles both SvelteKit and @donkeylabs/server requests.
+ */
+export function createUnifiedServer(config) {
+  const {
+    svelteServer,
+    donkeylabsServer,
+    port,
+    host,
+    clientDir: clientDirRelative,
+    prerenderedDir: prerenderedDirRelative,
+    development = false,
+  } = config;
+
+  // Resolve paths relative to this script's directory
+  const clientDir = resolve(__dirname, clientDirRelative);
+  const prerenderedDir = resolve(__dirname, prerenderedDirRelative);
+
+  // Get services and core from @donkeylabs/server for injection into SvelteKit
+  const services = donkeylabsServer.getServices();
+  const core = donkeylabsServer.getCore();
+
+  Bun.serve({
+    port,
+    hostname: host,
+
+    async fetch(req, server) {
+      const url = new URL(req.url);
+      const pathname = url.pathname;
+      const ip = extractClientIP(req, server.requestIP(req)?.address);
+
+      // 1. Handle CORS preflight for API routes
+      if (req.method === "OPTIONS") {
+        return new Response(null, {
+          status: 204,
+          headers: getCorsHeaders(),
+        });
+      }
+
+      // 2. API routes (POST /route.name)
+      if (req.method === "POST") {
+        const routeName = pathname.slice(1); // Remove leading /
+
+        // Check if this is a registered API route
+        if (donkeylabsServer.hasRoute(routeName)) {
+          const response = await donkeylabsServer.handleRequest(req, routeName, ip, {
+            corsHeaders: getCorsHeaders(),
+          });
+          if (response) return response;
+        }
+      }
+
+      // 3. SSE endpoint
+      if (pathname === "/sse" && req.method === "GET") {
+        return handleSSE(req, core, ip);
+      }
+
+      // 4. Static assets (/_app/*, etc.)
+      if (isStaticAsset(pathname)) {
+        const staticResponse = await serveStatic(clientDir, pathname);
+        if (staticResponse) return staticResponse;
+      }
+
+      // 5. Prerendered pages
+      const prerenderedResponse = await servePrerendered(prerenderedDir, pathname);
+      if (prerenderedResponse) return prerenderedResponse;
+
+      // 6. SvelteKit pages
+      return handleSvelteKit(req, svelteServer, {
+        services,
+        core,
+        ip,
+        donkeylabsServer,
+      });
+    },
+  });
+}
+
+function isStaticAsset(pathname) {
+  return (
+    pathname.startsWith("/_app/") ||
+    pathname.startsWith("/static/") ||
+    pathname === "/favicon.ico" ||
+    pathname === "/robots.txt" ||
+    pathname === "/sitemap.xml" ||
+    /\\.(js|css|png|jpg|jpeg|gif|svg|ico|woff|woff2|ttf|eot|webp|avif|json|webmanifest)$/.test(pathname)
+  );
+}
+
+async function serveStatic(clientDir, pathname) {
+  const filePath = clientDir + pathname;
+  const file = Bun.file(filePath);
+
+  if (await file.exists()) {
+    // Check for precompressed versions
+    const brFile = Bun.file(filePath + ".br");
+    const gzFile = Bun.file(filePath + ".gz");
+
+    if (await brFile.exists()) {
+      return new Response(brFile, {
+        headers: {
+          "Content-Type": file.type || "application/octet-stream",
+          "Content-Encoding": "br",
+          "Cache-Control": "public, max-age=31536000, immutable",
+        },
+      });
+    }
+
+    if (await gzFile.exists()) {
+      return new Response(gzFile, {
+        headers: {
+          "Content-Type": file.type || "application/octet-stream",
+          "Content-Encoding": "gzip",
+          "Cache-Control": "public, max-age=31536000, immutable",
+        },
+      });
+    }
+
+    return new Response(file, {
+      headers: {
+        "Content-Type": file.type || "application/octet-stream",
+        "Cache-Control": "public, max-age=31536000, immutable",
+      },
+    });
+  }
+
+  return null;
+}
+
+async function servePrerendered(prerenderedDir, pathname) {
+  let filePath = prerenderedDir + pathname;
+  if (!pathname.endsWith(".html") && !pathname.includes(".")) {
+    filePath = prerenderedDir + (pathname === "/" ? "/index" : pathname) + ".html";
+  }
+
+  const file = Bun.file(filePath);
+  if (await file.exists()) {
+    return new Response(file, {
+      headers: {
+        "Content-Type": "text/html",
+        "Cache-Control": "public, max-age=0, must-revalidate",
+      },
+    });
+  }
+
+  return null;
+}
+
+async function handleSvelteKit(req, svelteServer, context) {
+  return svelteServer.respond(req, {
+    getClientAddress: () => context.ip,
+    platform: {
+      donkeylabs: {
+        services: context.services,
+        core: context.core,
+        // Direct route handler for SSR API calls (no HTTP!)
+        handleRoute: async (routeName, input) => {
+          return context.donkeylabsServer.callRoute(routeName, input, context.ip);
+        },
+      },
+    },
+  });
+}
+
+function handleSSE(req, core, ip) {
+  const url = new URL(req.url);
+  const channels = url.searchParams.get("channels")?.split(",") || [];
+
+  if (channels.length === 0) {
+    return new Response("Missing channels parameter", { status: 400 });
+  }
+
+  const lastEventId = req.headers.get("Last-Event-ID") || undefined;
+  const { client, response } = core.sse.addClient({ lastEventId });
+
+  for (const channel of channels) {
+    core.sse.subscribe(client.id, channel);
+  }
+
+  req.signal.addEventListener("abort", () => {
+    core.sse.removeClient(client.id);
+  });
+
+  const headers = new Headers(response.headers);
+  const corsHeaders = getCorsHeaders();
+  Object.entries(corsHeaders).forEach(([k, v]) => headers.set(k, v));
+
+  return new Response(response.body, {
+    status: response.status,
+    headers,
+  });
+}
+
+function extractClientIP(req, socketIP) {
+  return (
+    req.headers.get("x-forwarded-for")?.split(",")[0]?.trim() ||
+    req.headers.get("x-real-ip") ||
+    socketIP ||
+    "127.0.0.1"
+  );
+}
+
+function getCorsHeaders() {
+  return {
+    "Access-Control-Allow-Origin": "*",
+    "Access-Control-Allow-Methods": "GET, POST, OPTIONS",
+    "Access-Control-Allow-Headers": "Content-Type, Authorization",
+  };
+}
+`;
+}
+
+// Re-export types
+export type { AdapterOptions as Options };

package/src/vite.ts

@@ -0,0 +1,359 @@
+/**
+ * Vite plugin for @donkeylabs/adapter-sveltekit dev server integration
+ *
+ * Supports two modes:
+ * - `bun --bun run dev`: Single-process mode (in-process, one port)
+ * - `bun run dev`: Subprocess mode (two processes, proxy)
+ */
+
+import type { Plugin, ViteDevServer } from "vite";
+import { spawn, type ChildProcess } from "node:child_process";
+import { resolve } from "node:path";
+import http from "node:http";
+
+export interface DevPluginOptions {
+  /**
+   * Path to your @donkeylabs/server entry file.
+   * This file should export a configured AppServer instance.
+   *
+   * @example "./src/server/index.ts"
+   */
+  serverEntry: string;
+
+  /**
+   * Port for the backend server (subprocess mode only).
+   * @default 3001
+   */
+  backendPort?: number;
+}
+
+// Check if running with Bun runtime (bun --bun)
+const isBunRuntime = typeof globalThis.Bun !== "undefined";
+
+// Global reference to the app server for SSR direct calls
+let globalAppServer: any = null;
+
+/**
+ * Get the global app server instance for SSR direct calls.
+ * This allows hooks to access the server without HTTP.
+ */
+export function getDevServer(): any {
+  return globalAppServer;
+}
+
+/**
+ * Vite plugin that integrates @donkeylabs/server with the dev server.
+ *
+ * - With `bun --bun run dev`: Runs in-process (single port, recommended)
+ * - With `bun run dev`: Spawns subprocess (two ports, fallback)
+ *
+ * @example
+ * // vite.config.ts
+ * import { donkeylabsDev } from "@donkeylabs/adapter-sveltekit/vite";
+ *
+ * export default defineConfig({
+ *   plugins: [
+ *     donkeylabsDev({ serverEntry: "./src/server/index.ts" }),
+ *     sveltekit()
+ *   ]
+ * });
+ */
+export function donkeylabsDev(options: DevPluginOptions): Plugin {
+  const { serverEntry, backendPort = 3001 } = options;
+
+  if (!serverEntry) {
+    throw new Error("donkeylabsDev: serverEntry option is required");
+  }
+
+  // State for subprocess mode
+  let backendProcess: ChildProcess | null = null;
+  let backendReady = false;
+
+  // State for in-process mode
+  let appServer: any = null;
+  let serverReady = false;
+
+  return {
+    name: "donkeylabs-dev",
+    enforce: "pre",
+
+    async configureServer(server: ViteDevServer) {
+      const serverEntryResolved = resolve(process.cwd(), serverEntry);
+
+      if (isBunRuntime) {
+        // ========== IN-PROCESS MODE (bun --bun run dev) ==========
+        // Import and initialize server directly - no subprocess, no proxy
+        console.log("[donkeylabs-dev] Starting in-process mode (Bun runtime detected)");
+
+        try {
+          const serverModule = await import(serverEntryResolved);
+          appServer = serverModule.server || serverModule.default;
+
+          if (!appServer) {
+            throw new Error("No server export found in " + serverEntry);
+          }
+
+          // Initialize without starting HTTP server
+          await appServer.initialize();
+          serverReady = true;
+          // Set global reference for SSR direct calls
+          globalAppServer = appServer;
+          console.log("[donkeylabs-dev] Server initialized (in-process mode)");
+        } catch (err) {
+          console.error("[donkeylabs-dev] Failed to initialize server:", err);
+          throw err;
+        }
+
+        // Return middleware setup function
+        return () => {
+          // In-process request handler
+          const inProcessMiddleware = async (req: any, res: any, next: any) => {
+            const url = req.url || "/";
+
+            // Handle SSE
+            if (req.method === "GET" && url.startsWith("/sse")) {
+              if (!serverReady || !appServer) return next();
+
+              const fullUrl = new URL(url, "http://localhost");
+              const channels = fullUrl.searchParams.get("channels")?.split(",").filter(Boolean) || [];
+              const lastEventId = req.headers["last-event-id"] || undefined;
+
+              const { client, response } = appServer.getCore().sse.addClient({ lastEventId });
+
+              for (const channel of channels) {
+                appServer.getCore().sse.subscribe(client.id, channel);
+              }
+
+              // Set SSE headers
+              res.writeHead(200, {
+                "Content-Type": "text/event-stream",
+                "Cache-Control": "no-cache",
+                "Connection": "keep-alive",
+                "Access-Control-Allow-Origin": "*",
+              });
+
+              // Stream SSE data
+              const reader = response.body?.getReader();
+              if (reader) {
+                const pump = async () => {
+                  try {
+                    while (true) {
+                      const { done, value } = await reader.read();
+                      if (done) break;
+                      res.write(value);
+                    }
+                  } catch {
+                    // Connection closed
+                  }
+                };
+                pump();
+              }
+
+              req.on("close", () => {
+                appServer.getCore().sse.removeClient(client.id);
+              });
+
+              return; // Don't call next()
+            }
+
+            // Handle API routes (POST)
+            if (req.method === "POST" && /^\/[a-zA-Z][a-zA-Z0-9_.]*$/.test(url)) {
+              if (!serverReady || !appServer) return next();
+
+              const routeName = url.slice(1);
+              if (!appServer.hasRoute(routeName)) return next();
+
+              // Collect body
+              let body = "";
+              req.on("data", (chunk: any) => (body += chunk));
+              req.on("end", async () => {
+                try {
+                  const input = body ? JSON.parse(body) : {};
+                  const ip = req.socket?.remoteAddress || "127.0.0.1";
+
+                  const result = await appServer.callRoute(routeName, input, ip);
+
+                  res.setHeader("Content-Type", "application/json");
+                  res.setHeader("Access-Control-Allow-Origin", "*");
+                  res.end(JSON.stringify(result));
+                } catch (err: any) {
+                  res.statusCode = err.status || 500;
+                  res.setHeader("Content-Type", "application/json");
+                  res.end(JSON.stringify({ error: err.message || "Internal error" }));
+                }
+              });
+
+              return; // Don't call next()
+            }
+
+            next();
+          };
+
+          // CORS preflight
+          const corsMiddleware = (req: any, res: any, next: any) => {
+            if (req.method === "OPTIONS") {
+              res.setHeader("Access-Control-Allow-Origin", "*");
+              res.setHeader("Access-Control-Allow-Methods", "GET, POST, OPTIONS");
+              res.setHeader("Access-Control-Allow-Headers", "Content-Type, Authorization");
+              res.statusCode = 204;
+              res.end();
+              return;
+            }
+            next();
+          };
+
+          // Add to front of middleware stack
+          const stack = (server.middlewares as any).stack;
+          if (stack && Array.isArray(stack)) {
+            stack.unshift({ route: "", handle: corsMiddleware });
+            stack.unshift({ route: "", handle: inProcessMiddleware });
+          } else {
+            server.middlewares.use(inProcessMiddleware);
+            server.middlewares.use(corsMiddleware);
+          }
+        };
+      } else {
+        // ========== SUBPROCESS MODE (bun run dev) ==========
+        // Spawn backend as separate process and proxy requests
+        console.log(`[donkeylabs-dev] Starting subprocess mode (backend on port ${backendPort})`);
+
+        const bootstrapCode = `
+          const serverModule = await import("${serverEntryResolved}");
+          const server = serverModule.server || serverModule.default;
+
+          if (!server) {
+            console.error("[donkeylabs-backend] No server export found");
+            process.exit(1);
+          }
+
+          server.port = ${backendPort};
+          await server.start();
+          console.log("[donkeylabs-backend] Server ready on port ${backendPort}");
+        `;
+
+        backendProcess = spawn("bun", ["--eval", bootstrapCode], {
+          stdio: ["pipe", "pipe", "pipe"],
+          env: { ...process.env, NODE_ENV: "development" },
+        });
+
+        backendProcess.stdout?.on("data", (data: Buffer) => {
+          const msg = data.toString().trim();
+          if (msg) {
+            console.log(msg);
+            if (msg.includes("Server ready") || msg.includes("Server running")) {
+              backendReady = true;
+            }
+          }
+        });
+
+        backendProcess.stderr?.on("data", (data: Buffer) => {
+          const msg = data.toString().trim();
+          if (msg) console.error(msg);
+        });
+
+        backendProcess.on("error", (err) => {
+          console.error("[donkeylabs-dev] Failed to start backend:", err);
+        });
+
+        backendProcess.on("exit", (code) => {
+          if (code !== 0 && code !== null) {
+            console.error(`[donkeylabs-dev] Backend exited with code ${code}`);
+          }
+          backendProcess = null;
+          backendReady = false;
+        });
+
+        server.httpServer?.on("close", () => {
+          if (backendProcess) {
+            backendProcess.kill();
+            backendProcess = null;
+          }
+        });
+
+        // Return middleware setup function
+        return () => {
+          const waitForBackend = new Promise<void>((resolve) => {
+            const check = () => (backendReady ? resolve() : setTimeout(check, 100));
+            setTimeout(check, 500);
+            setTimeout(() => {
+              if (!backendReady) {
+                console.warn("[donkeylabs-dev] Backend startup timeout");
+                resolve();
+              }
+            }, 10000);
+          });
+
+          // Proxy middleware
+          const proxyMiddleware = (req: any, res: any, next: any) => {
+            const url = req.url || "/";
+            const isApiRoute = req.method === "POST" && /^\/[a-zA-Z][a-zA-Z0-9_.]*$/.test(url);
+
+            if (!isApiRoute) return next();
+
+            waitForBackend.then(() => {
+              const proxyReq = http.request(
+                {
+                  hostname: "localhost",
+                  port: backendPort,
+                  path: url,
+                  method: req.method,
+                  headers: { ...req.headers, host: `localhost:${backendPort}` },
+                },
+                (proxyRes) => {
+                  res.setHeader("Access-Control-Allow-Origin", "*");
+                  res.statusCode = proxyRes.statusCode || 200;
+                  for (const [k, v] of Object.entries(proxyRes.headers)) {
+                    if (v) res.setHeader(k, v);
+                  }
+                  proxyRes.pipe(res);
+                }
+              );
+
+              proxyReq.on("error", (err) => {
+                console.error(`[donkeylabs-dev] Proxy error:`, err.message);
+                res.statusCode = 502;
+                res.end(JSON.stringify({ error: "Backend unavailable" }));
+              });
+
+              req.pipe(proxyReq);
+            });
+          };
+
+          const corsMiddleware = (req: any, res: any, next: any) => {
+            if (req.method === "OPTIONS") {
+              res.setHeader("Access-Control-Allow-Origin", "*");
+              res.setHeader("Access-Control-Allow-Methods", "GET, POST, OPTIONS");
+              res.setHeader("Access-Control-Allow-Headers", "Content-Type, Authorization");
+              res.statusCode = 204;
+              res.end();
+              return;
+            }
+            next();
+          };
+
+          const stack = (server.middlewares as any).stack;
+          if (stack && Array.isArray(stack)) {
+            stack.unshift({ route: "", handle: corsMiddleware });
+            stack.unshift({ route: "", handle: proxyMiddleware });
+          } else {
+            server.middlewares.use(proxyMiddleware);
+            server.middlewares.use(corsMiddleware);
+          }
+        };
+      }
+    },
+
+    async closeBundle() {
+      if (backendProcess) {
+        backendProcess.kill();
+        backendProcess = null;
+      }
+      if (appServer) {
+        await appServer.shutdown?.();
+        appServer = null;
+      }
+    },
+  };
+}
+
+export default donkeylabsDev;