@oselvar/sveltekit-add-worker-exports 0.1.2 → 0.2.0

package/README.md

@@ -16,26 +16,62 @@ pnpm add -D @oselvar/sveltekit-add-worker-exports
 
 ## Usage
 
-Create a file that exports your Durable Object and/or Workflow classes:
+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.
 
 ```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> {
-    // Route WebSocket upgrades to Durable Objects (used during dev)
-    const url = new URL(request.url);
-    const match = url.pathname.match(/^\/ws\/(.+)$/);
-    if (match && request.headers.get('Upgrade') === 'websocket') {
-      const id = env.MY_DO.idFromName(match[1]);
-      return env.MY_DO.get(id).fetch(request);
-    }
-    return new Response('Not found', { status: 404 });
+    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.
+
 Add the plugin to your `vite.config.ts` **after** `sveltekit()`:
 
 ```typescript
@@ -51,6 +87,23 @@ export default defineConfig({
 });
 ```
 
+Point `adapter-cloudflare`'s platform proxy at the generated `.platform-proxy-wrangler.jsonc`. This is a copy of your wrangler config with internal Durable Object bindings, Workflows, and migrations stripped — those are served by the dev sidecar on a separate port, and `getPlatformProxy` would otherwise log warnings about classes it can't load:
+
+```javascript
+// svelte.config.js
+import adapter from '@sveltejs/adapter-cloudflare';
+
+export default {
+  kit: {
+    adapter: adapter({
+      platformProxy: {
+        configPath: '.platform-proxy-wrangler.jsonc'
+      }
+    })
+  }
+};
+```
+
 ### 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:
@@ -78,6 +131,29 @@ declare global {
 
 The plugin auto-discovers your `wrangler.jsonc` (or `wrangler.toml`) and reads DO bindings, migrations, and compatibility settings from it. It overrides only the `main` entry point to use your source file instead of the SvelteKit build output.
 
+### 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:
+
+```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.
+
+A handy shortcut is to add a `preview` script to `package.json`:
+
+```json
+{
+  "scripts": {
+    "preview": "wrangler dev"
+  }
+}
+```
+
+> 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.
+
 ## Options
 
 | Option | Type | Required | Default | Description |
@@ -111,6 +187,29 @@ The plugin reads your wrangler config, creates a temporary config with `main` po
 - Real workerd runtime (not emulated)
 - Hot-reload when you change DO code
 - Same WebSocket protocol as production
+- Fully typed Durable Object bindings (see below)
+
+### Generating typed bindings
+
+The dev plugin creates a temporary `.dev-worker-wrangler.jsonc` with `main` pointing to your source entry point. You can use this to generate fully generic Cloudflare types:
+
+```bash
+wrangler types --config .dev-worker-wrangler.jsonc
+```
+
+This produces typed DO bindings like `DurableObjectNamespace<MyDurableObject>` instead of the untyped `DurableObjectNamespace` you get from the default `wrangler.jsonc` (whose `main` points to the SvelteKit build output, which doesn't exist during dev).
+
+Add this to your `package.json` scripts for convenience:
+
+```json
+{
+  "scripts": {
+    "types": "wrangler types --config .dev-worker-wrangler.jsonc"
+  }
+}
+```
+
+Note: the `.dev-worker-wrangler.jsonc` file is generated when the dev server starts. Run `pnpm dev` at least once before running `wrangler types`.
 
 ## Why this exists
 

package/dist/index.js

@@ -76,6 +76,7 @@ function devPlugin(options) {
     const devPort = options.devPort ?? DEFAULT_DEV_PORT;
     let worker = null;
     let tempConfigPath = null;
+    let proxyConfigPath = null;
     return {
         name: 'add-worker-exports-dev',
         apply: 'serve',
@@ -99,6 +100,21 @@ function devPlugin(options) {
             delete devConfig.assets;
             tempConfigPath = resolve('.dev-worker-wrangler.jsonc');
             await writeFile(tempConfigPath, JSON.stringify(devConfig, null, '\t'));
+            // Also write a wrangler config for adapter-cloudflare's getPlatformProxy
+            // (used by vite dev for platform.env). It can't run internal DOs or
+            // Workflows -- those are served by the sidecar above. Strip them so it
+            // doesn't emit warnings about classes it can't load.
+            const proxyConfig = parseJsonc(rawJson);
+            if (proxyConfig.durable_objects?.bindings) {
+                proxyConfig.durable_objects.bindings = proxyConfig.durable_objects.bindings.filter((b) => b.script_name);
+                if (proxyConfig.durable_objects.bindings.length === 0) {
+                    delete proxyConfig.durable_objects;
+                }
+            }
+            delete proxyConfig.workflows;
+            delete proxyConfig.migrations;
+            proxyConfigPath = resolve('.platform-proxy-wrangler.jsonc');
+            await writeFile(proxyConfigPath, JSON.stringify(proxyConfig, null, '\t'));
             worker = await unstable_startWorker({ config: tempConfigPath });
             server.httpServer?.on('close', async () => {
                 if (worker) {
@@ -108,6 +124,9 @@ function devPlugin(options) {
                 if (tempConfigPath) {
                     await unlink(tempConfigPath).catch(() => { });
                 }
+                if (proxyConfigPath) {
+                    await unlink(proxyConfigPath).catch(() => { });
+                }
             });
         }
     };

package/package.json

@@ -1,52 +1,51 @@
 {
-	"name": "@oselvar/sveltekit-add-worker-exports",
-	"version": "0.1.2",
-	"description": "Vite plugin that adds Durable Object and Workflow exports to SvelteKit Cloudflare workers",
-	"type": "module",
-	"publishConfig": {
-		"access": "public"
-	},
-	"exports": {
-		".": {
-			"types": "./dist/index.d.ts",
-			"import": "./dist/index.js"
-		}
-	},
-	"files": [
-		"dist"
-	],
-	"license": "MIT",
-	"repository": {
-		"type": "git",
-		"url": "https://github.com/oselvar/sveltekit-add-worker-exports"
-	},
-	"keywords": [
-		"sveltekit",
-		"cloudflare",
-		"workers",
-		"durable-objects",
-		"workflows",
-		"vite-plugin"
-	],
-	"peerDependencies": {
-		"esbuild": ">=0.17",
-		"vite": ">=5",
-		"wrangler": ">=4"
-	},
-	"devDependencies": {
-		"@types/node": "^22.0.0",
-		"esbuild": "^0.25.0",
-		"np": "^11.2.0",
-		"typescript": "^5.0.0",
-		"vite": "^6.0.0",
-		"wrangler": "^4.84.0"
-	},
-	"scripts": {
-		"build": "tsc",
-		"test": "tsc --noEmit",
-		"prepublishOnly": "tsc"
-	},
-	"dependencies": {
-		"jsonc-parser": "^3.3.1"
-	}
-}
+  "name": "@oselvar/sveltekit-add-worker-exports",
+  "version": "0.2.0",
+  "description": "Vite plugin that adds Durable Object and Workflow exports to SvelteKit Cloudflare workers",
+  "type": "module",
+  "publishConfig": {
+    "access": "public"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/oselvar/sveltekit-add-worker-exports.git"
+  },
+  "keywords": [
+    "sveltekit",
+    "cloudflare",
+    "workers",
+    "durable-objects",
+    "workflows",
+    "vite-plugin"
+  ],
+  "peerDependencies": {
+    "esbuild": ">=0.17",
+    "vite": ">=5",
+    "wrangler": ">=4"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "esbuild": "^0.25.0",
+    "np": "^11.2.0",
+    "typescript": "^5.0.0",
+    "vite": "^6.0.0",
+    "wrangler": "^4.84.0"
+  },
+  "dependencies": {
+    "jsonc-parser": "^3.3.1"
+  },
+  "scripts": {
+    "build": "tsc",
+    "test": "tsc --noEmit"
+  }
+}