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

package/README.md

@@ -16,26 +16,59 @@ 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 { default } from './devHandler';
+```
+
+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
@@ -78,6 +111,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 +167,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/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.1.3",
+  "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"
+  }
+}