@oselvar/sveltekit-add-worker-exports 1.0.0 → 2.1.0

package/README.md

@@ -1,20 +1,21 @@
 # @oselvar/sveltekit-add-worker-exports
 
-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.
+A Vite plugin that makes any class-based Cloudflare Worker export (Durable Objects, Workflows, `WorkerEntrypoint` RPC, voice agents, …) and any non-fetch handler (`scheduled`, `queue`, `email`, `tail`, `trace`) 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 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.
+**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**, and non-fetch handlers (`scheduled`, `queue`, `email`, …) to be **methods on the default export**. This plugin post-processes the build output to merge both kinds onto SvelteKit's worker.
 
-**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.
+**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. The sidecar also exposes `/__scheduled` so `scheduled` handlers can be fired manually in dev — see [Scheduled, queue, email, tail handlers](#scheduled-queue-email-tail-handlers).
 
 ## 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:
+The plugin is binding-agnostic: if Cloudflare resolves it through a named class export plus a `wrangler.jsonc` binding, or through a method on the default export, the plugin handles it. Confirmed working:
 
 - Durable Objects
 - Workflows (`WorkflowEntrypoint`)
 - Voice agents
+- `scheduled` (cron triggers) — see [Scheduled, queue, email, tail handlers](#scheduled-queue-email-tail-handlers)
 
-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.
+It should also work with `WorkerEntrypoint` RPC and any future class-based export that follows the same export-plus-binding pattern, as well as `queue`, `email`, `tail`, and `trace` — anything Cloudflare invokes as a method on the worker's default export. 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
 
@@ -254,10 +255,10 @@ The plugin reads your wrangler config, creates a temporary config with `main` po
 
 ### Generating typed bindings
 
-The dev plugin creates a temporary `.types-worker-wrangler.jsonc` with `main` pointing to your source entry point. Use it to generate fully generic Cloudflare types:
+The dev plugin creates a temporary `.dev-worker-wrangler.jsonc` with `main` pointing to your source entry point. Use it to generate fully generic Cloudflare types:
 
 ```bash
-wrangler types --config .types-worker-wrangler.jsonc
+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).
@@ -267,12 +268,12 @@ Add this to your `package.json` scripts for convenience:
 ```json
 {
   "scripts": {
-    "types": "wrangler types --config .types-worker-wrangler.jsonc"
+    "types": "wrangler types --config .dev-worker-wrangler.jsonc"
   }
 }
 ```
 
-Note: the `.types-worker-wrangler.jsonc` file is generated when the dev server starts. Run `pnpm dev` at least once before running `wrangler types`.
+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
 
@@ -286,7 +287,7 @@ Once that PR lands, `@cloudflare/vite-plugin` handles everything this plugin doe
 
 - **Build:** the plugin bundles a single worker entry that exports `default` + named classes directly — no `_worker.js` post-processing, no second esbuild pass to merge exports.
 - **Dev:** Durable Objects and Workflows run in the same worker as SvelteKit on real workerd, hot-reloaded — no sidecar via `unstable_startWorker`, no platform-proxy `script_name` rewrite, no separate WebSocket port, no dev registry routing.
-- **Types:** `wrangler types` resolves typed bindings (`DurableObjectNamespace<MyDO>`) from the user entry, no `.types-worker-wrangler.jsonc` indirection.
+- **Types:** `wrangler types` resolves typed bindings (`DurableObjectNamespace<MyDO>`) from the user entry, no `.dev-worker-wrangler.jsonc` indirection.
 
 Side note: [cloudflare/workers-sdk#14013](https://github.com/cloudflare/workers-sdk/pull/14013) introduces an experimental `cloudflare.config.ts` flow (typed `exports` API) where the Durable Object branch currently throws `"Durable Object exports are not currently supported."` (see [`convert.ts`](https://github.com/cloudflare/workers-sdk/blob/main/packages/config/src/convert.ts)) and Workflows are commented out. This is a separate, opt-in config surface — the standard `wrangler.jsonc` path that kit#15627 uses already supports DO and Workflow named exports, so this limitation does **not** gate retirement.
 

package/dist/index.d.ts

@@ -21,6 +21,14 @@
  * @see https://github.com/sveltejs/kit/issues/1712
  */
 import type { Plugin } from 'vite';
+/**
+ * Parses a wrangler config file. Picks the parser by extension:
+ * `.toml` uses smol-toml; everything else (`.jsonc`, `.json`, or no
+ * extension) uses jsonc-parser, which handles plain JSON fine.
+ *
+ * Exported for tests; the dev plugin uses it via the configureServer hook.
+ */
+export declare function parseWranglerConfig(path: string, contents: string): unknown;
 export interface AddWorkerExportsOptions {
     /** File that exports Durable Object and/or Workflow classes */
     entryPoint: string;
@@ -30,6 +38,17 @@ export interface AddWorkerExportsOptions {
     wranglerConfig?: string;
     /** Port for the dev worker server (default: 8787) */
     devPort?: number;
+    /**
+     * Handles each structured log line emitted by the sidecar worker (one entry
+     * per `console.log` / `console.error` / etc. call). When omitted, a default
+     * handler prints each line to the host's stdout (or stderr for `error`
+     * level) prefixed with the sidecar name. Pass `() => {}` to silence.
+     */
+    structuredLogsHandler?: (log: {
+        level: string;
+        message: string;
+        timestamp: number;
+    }) => void;
 }
 /**
  * Returns two Vite plugins: one for build (patches _worker.js) and one for

package/dist/index.js

@@ -28,6 +28,17 @@ import { homedir } from 'node:os';
 import { join, resolve } from 'node:path';
 import { parse as parseJsonc } from 'jsonc-parser';
 import { getNodeCompat } from 'miniflare';
+import { parse as parseToml } from 'smol-toml';
+/**
+ * Parses a wrangler config file. Picks the parser by extension:
+ * `.toml` uses smol-toml; everything else (`.jsonc`, `.json`, or no
+ * extension) uses jsonc-parser, which handles plain JSON fine.
+ *
+ * Exported for tests; the dev plugin uses it via the configureServer hook.
+ */
+export function parseWranglerConfig(path, contents) {
+    return path.endsWith('.toml') ? parseToml(contents) : parseJsonc(contents);
+}
 const DEFAULT_DEV_PORT = 8787;
 /**
  * Mirrors wrangler's internal getRegistryPath() — wrangler doesn't export it.
@@ -133,11 +144,12 @@ function devPlugin(options) {
     let worker = null;
     let tempConfigPath = null;
     let proxyConfigPath = null;
-    let typesConfigPath = null;
     async function readRawConfig() {
         const { unstable_readConfig } = await import('wrangler');
         const parsed = unstable_readConfig(options.wranglerConfig ? { config: options.wranglerConfig } : {});
-        return readFile(parsed.configPath, 'utf-8');
+        const path = parsed.configPath;
+        const contents = await readFile(path, 'utf-8');
+        return { path, contents };
     }
     return {
         name: 'add-worker-exports-dev',
@@ -151,8 +163,8 @@ function devPlugin(options) {
         },
         async configureServer(server) {
             const { unstable_startWorker } = await import('wrangler');
-            const rawJson = await readRawConfig();
-            const baseConfig = parseJsonc(rawJson);
+            const { path: configPath, contents } = await readRawConfig();
+            const baseConfig = parseWranglerConfig(configPath, contents);
             const sidecarName = `${baseConfig.name ?? 'sveltekit'}-dev-worker`;
             // When CLOUDFLARE_ENV is set, wrangler suffixes the registered
             // worker name with `-${env}` (see appendEnvName in wrangler), so
@@ -167,15 +179,12 @@ function devPlugin(options) {
             devConfig.main = options.entryPoint;
             devConfig.dev = { ...devConfig.dev, port: devPort };
             delete devConfig.assets;
-            // Serialised dev config is reused verbatim as the `wrangler types`
-            // config — the user can run `wrangler types --config
-            // .types-worker-wrangler.jsonc` to get typed bindings like
+            // The user can also pass this file to `wrangler types --config
+            // .dev-worker-wrangler.jsonc` to get typed bindings like
             // DurableObjectNamespace<EchoDO> resolved from the source entry.
             const devConfigJson = JSON.stringify(devConfig, null, '\t');
             tempConfigPath = resolve('.dev-worker-wrangler.jsonc');
-            typesConfigPath = resolve('.types-worker-wrangler.jsonc');
             await writeFile(tempConfigPath, devConfigJson);
-            await writeFile(typesConfigPath, devConfigJson);
             // Write a wrangler config for adapter-cloudflare's getPlatformProxy
             // (used by vite dev for platform.env). It can't run internal DOs or
             // Workflows itself -- those are served by the sidecar above. Rewrite
@@ -201,6 +210,7 @@ function devPlugin(options) {
             delete activeScope.migrations;
             proxyConfigPath = resolve('.platform-proxy-wrangler.jsonc');
             await writeFile(proxyConfigPath, JSON.stringify(proxyConfig, null, '\t'));
+            const structuredLogsHandler = options.structuredLogsHandler ?? makeDefaultWorkerLogHandler(sidecarName);
             worker = await unstable_startWorker({
                 config: tempConfigPath,
                 // `testScheduled` mounts a `/__scheduled` endpoint on the sidecar
@@ -208,7 +218,19 @@ function devPlugin(options) {
                 // never auto-fires crons. Curl
                 // `http://localhost:<devPort>/__scheduled?cron=*+*+*+*+*` to
                 // trigger your `scheduled` handler.
-                dev: { registry: getWranglerRegistryPath(), testScheduled: true },
+                //
+                // `structuredLogsHandler` (added in wrangler 4.99) routes each
+                // worker log line through `onWorkerLog`. Without it, wrangler
+                // pipes worker logs through its own Logger which can get
+                // swallowed when `unstable_startWorker` is driven
+                // programmatically — `console.log` inside the worker
+                // disappears. Cast is needed because peer wrangler types may
+                // be older.
+                dev: {
+                    registry: getWranglerRegistryPath(),
+                    testScheduled: true,
+                    structuredLogsHandler
+                },
                 build: {
                     nodejsCompatMode: (parsedConfig) => getNodejsCompatMode(parsedConfig.compatibility_date, parsedConfig.compatibility_flags)
                 }
@@ -224,13 +246,22 @@ function devPlugin(options) {
                 if (proxyConfigPath) {
                     await unlink(proxyConfigPath).catch(() => { });
                 }
-                if (typesConfigPath) {
-                    await unlink(typesConfigPath).catch(() => { });
-                }
             });
         }
     };
 }
+/**
+ * Default handler for sidecar worker logs. Writes each line to stdout (or
+ * stderr for `error` level) tagged with the sidecar name so it's obvious
+ * which process produced it.
+ */
+function makeDefaultWorkerLogHandler(sidecarName) {
+    const prefix = `[${sidecarName}]`;
+    return ({ level, message }) => {
+        const stream = level === 'error' ? process.stderr : process.stdout;
+        stream.write(`${prefix} ${message}\n`);
+    };
+}
 async function exists(path) {
     try {
         await access(path);

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@oselvar/sveltekit-add-worker-exports",
-	"version": "1.0.0",
+	"version": "2.1.0",
 	"description": "Vite plugin that adds Durable Object and Workflow exports to SvelteKit Cloudflare workers",
 	"type": "module",
 	"publishConfig": {
@@ -37,22 +37,24 @@
 	},
 	"devDependencies": {
 		"@release-it/conventional-changelog": "^11.0.1",
-		"@sveltejs/kit": "^2.62.0",
-		"@types/node": "^25.9.1",
+		"@sveltejs/kit": "^2.64.0",
+		"@types/node": "^25.9.2",
 		"esbuild": "^0.28.0",
-		"miniflare": "^4.20260601.0",
+		"miniflare": "^4.20260609.0",
 		"release-it": "^20.2.0",
 		"typescript": "^6.0.3",
 		"vite": "^8.0.16",
-		"wrangler": "^4.98.0"
+		"vitest": "^4.1.8",
+		"wrangler": "^4.99.0"
 	},
 	"scripts": {
 		"build": "tsc",
-		"test": "tsc --noEmit",
+		"test": "vitest run && tsc --noEmit",
 		"prepublishOnly": "tsc",
 		"release": "release-it"
 	},
 	"dependencies": {
-		"jsonc-parser": "^3.3.1"
+		"jsonc-parser": "^3.3.1",
+		"smol-toml": "^1.6.1"
 	}
 }

package/dist/hooks.d.ts

@@ -1,10 +0,0 @@
-/**
- * SvelteKit `Handle` re-exported for users.
- *
- * Kept as a no-op for backwards compatibility. Wrangler 4.98.0 fixed
- * cross-worker workflow routing in `getPlatformProxy`
- * (cloudflare/workers-sdk#13863), so `platform.env.MY_WORKFLOW` is now a
- * real binding in both dev and production — no synthesis required.
- */
-import type { Handle } from '@sveltejs/kit';
-export declare const handle: Handle;

package/dist/hooks.js

@@ -1,9 +0,0 @@
-/**
- * SvelteKit `Handle` re-exported for users.
- *
- * Kept as a no-op for backwards compatibility. Wrangler 4.98.0 fixed
- * cross-worker workflow routing in `getPlatformProxy`
- * (cloudflare/workers-sdk#13863), so `platform.env.MY_WORKFLOW` is now a
- * real binding in both dev and production — no synthesis required.
- */
-export const handle = ({ event, resolve }) => resolve(event);