@oselvar/sveltekit-add-worker-exports 0.3.3 → 0.3.4

package/README.md

@@ -1,10 +1,20 @@
 # @oselvar/sveltekit-add-worker-exports
 
-A Vite plugin that makes Durable Objects and Workflows work with SvelteKit on Cloudflare, in both dev and production.
+A Vite plugin that makes any class-based Cloudflare Worker export (Durable Objects, Workflows, `WorkerEntrypoint` RPC, voice agents, …) work with SvelteKit on Cloudflare, in both dev and production.
 
-**Build mode:** SvelteKit's `adapter-cloudflare` generates `_worker.js` with only a default export (the fetch handler). Cloudflare Workers requires Durable Object and Workflow classes to be **named exports**. This plugin post-processes the build output to merge your named exports with SvelteKit's default export.
+**Build mode:** SvelteKit's `adapter-cloudflare` generates `_worker.js` with only a default export (the fetch handler). Cloudflare Workers requires class-based bindings (Durable Objects, Workflows, `WorkerEntrypoint`, etc.) to be **named exports**. This plugin post-processes the build output to merge your named exports with SvelteKit's default export.
 
-**Dev mode:** `getPlatformProxy` (used by `adapter-cloudflare` in dev) can't run internal Durable Objects or Workflows. This plugin starts a separate wrangler dev server that runs the real DO/Workflow worker with hot-reload. SvelteKit `+server.ts` handlers call DOs through `platform.env.MY_DO.<rpc>()` as usual — the plugin rewrites those bindings to point at the sidecar via wrangler's dev registry, so cross-worker calls Just Work. Clients can also connect directly to the sidecar via WebSocket on a separate port (see below).
+**Dev mode:** `getPlatformProxy` (used by `adapter-cloudflare` in dev) can't run internal Durable Objects, Workflows, or other class-based bindings. This plugin starts a separate wrangler dev server that runs the real worker with hot-reload. SvelteKit `+server.ts` handlers call bindings through `platform.env.MY_BINDING.<rpc>()` as usual — the plugin rewrites those bindings to point at the sidecar via wrangler's dev registry, so cross-worker calls Just Work. WebSocket clients in dev connect to the sidecar directly on a separate port — see [WebSockets](#websockets) below.
+
+## What this works with
+
+The plugin is binding-agnostic: if Cloudflare resolves it through a named class export plus a `wrangler.jsonc` binding, the plugin handles it. Confirmed working:
+
+- Durable Objects
+- Workflows (`WorkflowEntrypoint`)
+- Voice agents
+
+It should also work with `WorkerEntrypoint` RPC and any future class-based export that follows the same export-plus-binding pattern. The examples below use Durable Objects and Workflows because they're the most common, but the wiring is the same for any class-based entrypoint — export the class from your entry point, declare the binding in `wrangler.jsonc`, and call it via `platform.env.MY_BINDING` in your routes.
 
 ## Install
 
@@ -16,61 +26,17 @@ pnpm add -D @oselvar/sveltekit-add-worker-exports
 
 ## Usage
 
-Create a worker entry point that exports your Durable Object classes and a default fetch handler. The fetch handler is only used by the wrangler dev server — in production, SvelteKit's route handlers handle all requests.
+Create a worker entry point that exports your class-based bindings:
 
 ```typescript
 // src/lib/server/index.ts
 export { MyDurableObject } from './MyDurableObject';
 export { MyWorkflow } from './MyWorkflow';
-export { default } from './devHandler';
 ```
 
 Workflow classes (extending `WorkflowEntrypoint`) are exported the same way as Durable Objects — the plugin merges them into `_worker.js` as named exports. Declare them in `wrangler.jsonc` under `workflows`, and they become available as bindings (e.g. `env.MY_WORKFLOW.create({ params })`) in both dev and production.
 
-Both the dev handler and the production SvelteKit route need to do the same thing: validate the upgrade header and forward the request to a Durable Object. Extract that into a small helper so the two callers stay in sync:
-
-```typescript
-// src/lib/server/forwardWebSocket.ts
-export async function forwardWebSocket<T extends Rpc.DurableObjectBranded | undefined>(
-  request: Request,
-  namespace: DurableObjectNamespace<T>,
-  name: string
-): Promise<Response> {
-  if (request.headers.get('upgrade') !== 'websocket') {
-    return new Response('Expected WebSocket', { status: 426 });
-  }
-  const id = namespace.idFromName(name);
-  return namespace.get(id).fetch(request);
-}
-```
-
-The dev handler parses the URL and delegates. It's only used by the wrangler dev sidecar:
-
-```typescript
-// src/lib/server/devHandler.ts
-import { forwardWebSocket } from './forwardWebSocket';
-
-export default {
-  async fetch(request: Request, env: Env): Promise<Response> {
-    const match = new URL(request.url).pathname.match(/^\/ws\/(.+)$/);
-    if (!match) return new Response('Not found', { status: 404 });
-    return forwardWebSocket(request, env.MY_DO, match[1]);
-  }
-};
-```
-
-In production, the dev handler is *not* used — SvelteKit serves the same path through a `+server.ts` route, which delegates to the same helper:
-
-```typescript
-// src/routes/ws/[id]/+server.ts
-import { forwardWebSocket } from '$lib/server/forwardWebSocket';
-import type { RequestHandler } from './$types';
-
-export const GET: RequestHandler = ({ params, request, platform }) =>
-  forwardWebSocket(request, platform!.env.MY_DO, params.id);
-```
-
-Now any change to the upgrade-and-forward logic (auth, rate-limiting, response shape) lives in one place and applies to both dev and production.
+If clients need to talk directly to the dev sidecar over HTTP (e.g. WebSockets), also export a default fetch handler — see [WebSockets](#websockets) below.
 
 Add the plugin to your `vite.config.ts` **after** `sveltekit()`:
 
@@ -104,36 +70,11 @@ export default {
 };
 ```
 
-### Dev mode: connecting to Durable Objects
-
-In dev mode, the plugin starts a wrangler dev server on a separate port and injects `__DEV_WORKER_PORT__` as a compile-time constant. Use it to connect your client:
-
-```typescript
-import { dev } from '$app/environment';
-
-let wsUrl: string;
-if (dev) {
-  wsUrl = `ws://${window.location.hostname}:${__DEV_WORKER_PORT__}/ws/${id}`;
-} else {
-  const protocol = window.location.protocol === 'https:' ? 'wss:' : 'ws:';
-  wsUrl = `${protocol}//${window.location.host}/ws/${id}`;
-}
-const ws = new WebSocket(wsUrl);
-```
-
-Add the type declaration to your `src/app.d.ts`:
-
-```typescript
-declare global {
-  const __DEV_WORKER_PORT__: number;
-}
-```
-
-The plugin auto-discovers your `wrangler.jsonc` (or `wrangler.toml`) and reads DO bindings, workflows, migrations, and compatibility settings from it. It overrides only the `main` entry point to point at your source entry.
+The plugin auto-discovers your `wrangler.jsonc` (or `wrangler.toml`) and reads bindings, workflows, migrations, and compatibility settings from it. It overrides only the `main` entry point to point at your source entry.
 
-### Dev mode: calling Workflows
+### Calling Workflows
 
-`+server.ts` calls workflows the same way it does in production:
+`+server.ts` calls workflows the same way in dev and production:
 
 ```typescript
 export const POST: RequestHandler = async ({ params, request, platform }) => {
@@ -149,14 +90,14 @@ The sidecar runs the real `WorkflowEntrypoint` class; calls reach it via the `sc
 
 ### Testing the production build locally
 
-`vite dev` exercises the dev handler via the wrangler-dev sidecar; it does *not* exercise your `+server.ts` route or the merged `_worker.js`. To verify the production wiring (named DO exports + SvelteKit routes in the same worker), run wrangler against the build output:
+`vite dev` exercises your code via the wrangler-dev sidecar; it does *not* exercise the merged `_worker.js`. To verify the production wiring (named class exports + SvelteKit routes in the same worker), run wrangler against the build output:
 
 ```bash
 pnpm build              # produces .svelte-kit/cloudflare/_worker.js with merged exports
 pnpm wrangler dev       # uses wrangler.jsonc → main: .svelte-kit/cloudflare/_worker.js
 ```
 
-This serves the exact bundle that gets deployed, with local Durable Object storage. Connect a WebSocket client to `ws://localhost:8787/ws/<id>` and confirm you get a `101 Switching Protocols` response — that proves the request flowed through the SvelteKit `+server.ts` and into your DO.
+This serves the exact bundle that gets deployed, with local Durable Object storage. Exercise whichever route calls your binding (HTTP, WebSocket, whatever your app uses) and confirm the response — that proves the request flowed through the SvelteKit `+server.ts` and into your class.
 
 A handy shortcut is to add a `preview` script to `package.json`:
 
@@ -170,6 +111,89 @@ A handy shortcut is to add a `preview` script to `package.json`:
 
 > Note: `vite preview` is *not* suitable here — it only serves static assets and cannot run Durable Objects. Always use `wrangler dev` to preview the production worker.
 
+## WebSockets
+
+`vite dev` doesn't proxy WebSocket upgrades to the wrangler-dev sidecar, so in dev mode the browser needs to connect to the sidecar directly. The plugin exposes the sidecar's port as a compile-time constant `__DEV_WORKER_PORT__` for exactly this.
+
+The pattern: one helper handles the upgrade-and-forward, called from both the dev sidecar's fetch handler and the production `+server.ts` route, so both code paths stay in sync.
+
+```typescript
+// src/lib/server/forwardWebSocket.ts
+export async function forwardWebSocket<T extends Rpc.DurableObjectBranded | undefined>(
+  request: Request,
+  namespace: DurableObjectNamespace<T>,
+  name: string
+): Promise<Response> {
+  if (request.headers.get('upgrade') !== 'websocket') {
+    return new Response('Expected WebSocket', { status: 426 });
+  }
+  const id = namespace.idFromName(name);
+  return namespace.get(id).fetch(request);
+}
+```
+
+The dev sidecar needs a default `fetch` handler to receive the direct connection:
+
+```typescript
+// src/lib/server/devHandler.ts
+import { forwardWebSocket } from './forwardWebSocket';
+
+export default {
+  async fetch(request: Request, env: Env): Promise<Response> {
+    const match = new URL(request.url).pathname.match(/^\/ws\/(.+)$/);
+    if (!match) return new Response('Not found', { status: 404 });
+    return forwardWebSocket(request, env.MY_DO, match[1]);
+  }
+};
+```
+
+Add it to the worker entry point as the default export:
+
+```typescript
+// src/lib/server/index.ts
+export { MyDurableObject } from './MyDurableObject';
+export { MyWorkflow } from './MyWorkflow';
+export { default } from './devHandler';
+```
+
+In production, the dev handler is *not* used — SvelteKit serves the same path through a `+server.ts` route, which delegates to the same helper:
+
+```typescript
+// src/routes/ws/[id]/+server.ts
+import { forwardWebSocket } from '$lib/server/forwardWebSocket';
+import type { RequestHandler } from './$types';
+
+export const GET: RequestHandler = ({ params, request, platform }) =>
+  forwardWebSocket(request, platform!.env.MY_DO, params.id);
+```
+
+Any change to the upgrade-and-forward logic (auth, rate-limiting, response shape) now lives in one place and applies to both dev and production.
+
+### Connecting from the client
+
+Use `__DEV_WORKER_PORT__` to pick between the sidecar (dev) and the SvelteKit route (production):
+
+```typescript
+import { dev } from '$app/environment';
+
+let wsUrl: string;
+if (dev) {
+  wsUrl = `ws://${window.location.hostname}:${__DEV_WORKER_PORT__}/ws/${id}`;
+} else {
+  const protocol = window.location.protocol === 'https:' ? 'wss:' : 'ws:';
+  wsUrl = `${protocol}//${window.location.host}/ws/${id}`;
+}
+const ws = new WebSocket(wsUrl);
+```
+
+Add the type declaration to your `src/app.d.ts`:
+
+```typescript
+declare global {
+  const __DEV_WORKER_PORT__: number;
+}
+```
+
 ## Options
 
 | Option | Type | Required | Default | Description |
@@ -229,7 +253,7 @@ Note: the `.types-worker-wrangler.jsonc` file is generated when the dev server s
 
 ## Why this exists
 
-SvelteKit's adapter-cloudflare does not support named exports from the worker entry point ([sveltejs/kit#1712](https://github.com/sveltejs/kit/issues/1712)). Additionally, `getPlatformProxy` (used for local dev) cannot run internal Durable Objects because it uses an empty worker script.
+SvelteKit's adapter-cloudflare does not support named exports from the worker entry point ([sveltejs/kit#1712](https://github.com/sveltejs/kit/issues/1712)) — which blocks every class-based Cloudflare binding, not just Durable Objects. Additionally, `getPlatformProxy` (used for local dev) cannot run internal class-based bindings because it uses an empty worker script.
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@oselvar/sveltekit-add-worker-exports",
-	"version": "0.3.3",
+	"version": "0.3.4",
 	"description": "Vite plugin that adds Durable Object and Workflow exports to SvelteKit Cloudflare workers",
 	"type": "module",
 	"publishConfig": {