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

package/README.md

@@ -111,6 +111,32 @@ 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.
 
+## Scheduled, queue, email, tail handlers
+
+Cloudflare invokes non-fetch handlers (`scheduled`, `queue`, `email`, `tail`, `trace`) as methods on the worker's default export, not as named exports. Put them on the `default` export of your entry point and the plugin merges them onto the production worker's default alongside SvelteKit's fetch handler:
+
+```typescript
+// src/lib/server/index.ts
+export { MyDurableObject } from './MyDurableObject';
+export default {
+  async scheduled(event: ScheduledEvent, env: Env, ctx: ExecutionContext) {
+    // runs from the cron triggers in wrangler.jsonc
+  }
+};
+```
+
+If you also need a dev-only `fetch` (e.g. for WebSocket upgrades), put it on the same default — the plugin keeps the non-`fetch` handlers and drops `fetch` in production. See [WebSockets](#websockets) below for the full shape.
+
+### Firing scheduled in dev
+
+Wrangler dev never auto-fires crons — `triggers.crons` in `wrangler.jsonc` is only honored on the real Cloudflare edge. The plugin enables `testScheduled` on the sidecar so you can invoke the handler manually:
+
+```bash
+curl 'http://localhost:8787/__scheduled?cron=*+*+*+*+*'
+```
+
+The `cron` query parameter (URL-encoded — `+` instead of spaces) is what gets passed to your handler as `event.cron`. Stdout from the sidecar lands in the vite terminal.
+
 ## 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.
@@ -132,12 +158,15 @@ export async function forwardWebSocket<T extends Rpc.DurableObjectBranded | unde
 }
 ```
 
-The dev sidecar needs a default `fetch` handler to receive the direct connection:
+Put a `fetch` on the entry's default export so the dev sidecar can receive the direct connection:
 
 ```typescript
-// src/lib/server/devHandler.ts
+// src/lib/server/index.ts
 import { forwardWebSocket } from './forwardWebSocket';
 
+export { MyDurableObject } from './MyDurableObject';
+export { MyWorkflow } from './MyWorkflow';
+
 export default {
   async fetch(request: Request, env: Env): Promise<Response> {
     const match = new URL(request.url).pathname.match(/^\/ws\/(.+)$/);
@@ -147,16 +176,7 @@ export default {
 };
 ```
 
-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:
+In production this `fetch` is dropped (SvelteKit owns request handling — the plugin's merge strips it). The same path is served through a `+server.ts` route that delegates to the same helper:
 
 ```typescript
 // src/routes/ws/[id]/+server.ts
@@ -211,11 +231,14 @@ The plugin runs in the `closeBundle` hook (after SvelteKit's adapter has generat
 
 1. Bundles your `entryPoint` with esbuild into `_extra_exports.js`
 2. Renames the original `_worker.js` to `_sveltekit_worker.js`
-3. Creates a new `_worker.js` that re-exports both:
+3. Creates a new `_worker.js` that re-exports the named exports and merges the entry's `default` handlers (`scheduled`, `queue`, `email`, …) onto the SvelteKit default:
 
 ```javascript
-export { default } from './_sveltekit_worker.js';
+import sveltekitWorker from './_sveltekit_worker.js';
+import * as extra from './_extra_exports.js';
 export * from './_extra_exports.js';
+const { fetch: _ignored, ...extraHandlers } = extra.default ?? {};
+export default { ...sveltekitWorker, ...extraHandlers };
 ```
 
 The operation is idempotent -- if `_sveltekit_worker.js` already exists, the plugin skips.
@@ -255,6 +278,18 @@ Note: the `.types-worker-wrangler.jsonc` file is generated when the dev server s
 
 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.
 
+## When this plugin can be retired
+
+This plugin is a stopgap. The single blocker for retirement is [sveltejs/kit#15627](https://github.com/sveltejs/kit/pull/15627) — which replaces `adapter-cloudflare`'s custom build with `@cloudflare/vite-plugin`. Open as of writing. Closes [#1712](https://github.com/sveltejs/kit/issues/1712), [#10496](https://github.com/sveltejs/kit/issues/10496), [#13692](https://github.com/sveltejs/kit/issues/13692), [#2963](https://github.com/sveltejs/kit/issues/2963), [#13300](https://github.com/sveltejs/kit/issues/13300), [#1519](https://github.com/sveltejs/kit/issues/1519).
+
+Once that PR lands, `@cloudflare/vite-plugin` handles everything this plugin does, natively:
+
+- **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.
+
+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.
+
 ## License
 
 MIT

package/dist/index.js

@@ -23,20 +23,12 @@
 import { build } from 'esbuild';
 import { existsSync } from 'node:fs';
 import { access, readFile, rename, writeFile, unlink } from 'node:fs/promises';
+import { builtinModules as NODE_BUILTINS } from 'node:module';
 import { homedir } from 'node:os';
 import { join, resolve } from 'node:path';
 import { parse as parseJsonc } from 'jsonc-parser';
+import { getNodeCompat } from 'miniflare';
 const DEFAULT_DEV_PORT = 8787;
-const NODE_BUILTINS = [
-    'assert', 'async_hooks', 'buffer', 'child_process', 'cluster', 'console',
-    'constants', 'crypto', 'dgram', 'diagnostics_channel', 'dns', 'domain',
-    'events', 'fs', 'fs/promises', 'http', 'http2', 'https', 'inspector',
-    'module', 'net', 'os', 'path', 'path/posix', 'path/win32', 'perf_hooks',
-    'process', 'punycode', 'querystring', 'readline', 'repl', 'stream',
-    'stream/consumers', 'stream/promises', 'stream/web', 'string_decoder',
-    'sys', 'timers', 'timers/promises', 'tls', 'trace_events', 'tty', 'url',
-    'util', 'util/types', 'v8', 'vm', 'wasi', 'worker_threads', 'zlib'
-];
 /**
  * Mirrors wrangler's internal getRegistryPath() — wrangler doesn't export it.
  * Workers register themselves under this path so cross-worker `script_name`
@@ -117,9 +109,22 @@ function buildPlugin(options) {
                 ],
                 outfile: exportsPath
             });
-            // Rename original worker and create merged entry point
+            // Rename original worker and create merged entry point.
+            //
+            // `export *` re-exports named exports only, so class-based bindings
+            // (DOs, Workflows, WorkerEntrypoint) from `_extra_exports.js` flow
+            // through. Non-fetch handlers (scheduled, queue, email, tail, trace)
+            // live on the user entry's `default` export — Cloudflare invokes
+            // them as methods on the worker's default object, not as named
+            // exports — so we spread them onto the SvelteKit default. `fetch`
+            // is dropped from the user default because SvelteKit owns request
+            // handling in production.
             await rename(workerPath, sveltekitPath);
-            await writeFile(workerPath, `export { default } from './_sveltekit_worker.js';\nexport * from './_extra_exports.js';\n`);
+            await writeFile(workerPath, `import sveltekitWorker from './_sveltekit_worker.js';\n` +
+                `import * as extra from './_extra_exports.js';\n` +
+                `export * from './_extra_exports.js';\n` +
+                `const { fetch: _ignored, ...extraHandlers } = extra.default ?? {};\n` +
+                `export default { ...sveltekitWorker, ...extraHandlers };\n`);
         }
     };
 }
@@ -147,15 +152,30 @@ function devPlugin(options) {
         async configureServer(server) {
             const { unstable_startWorker } = await import('wrangler');
             const rawJson = await readRawConfig();
-            const sidecarName = `${parseJsonc(rawJson).name ?? 'sveltekit'}-dev-worker`;
+            const baseConfig = parseJsonc(rawJson);
+            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
+            // cross-worker `script_name` lookups must use the suffixed name.
+            // We don't suffix `devConfig.name` itself — wrangler does that
+            // based on CLOUDFLARE_ENV when starting the sidecar.
+            const envName = process.env.CLOUDFLARE_ENV;
+            const registeredSidecarName = envName ? `${sidecarName}-${envName}` : sidecarName;
             // Copy the raw config and override main, name, and dev port
-            const devConfig = parseJsonc(rawJson);
+            const devConfig = structuredClone(baseConfig);
             devConfig.name = sidecarName;
             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
+            // DurableObjectNamespace<EchoDO> resolved from the source entry.
+            const devConfigJson = JSON.stringify(devConfig, null, '\t');
             tempConfigPath = resolve('.dev-worker-wrangler.jsonc');
-            await writeFile(tempConfigPath, JSON.stringify(devConfig, null, '\t'));
+            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
@@ -163,30 +183,32 @@ function devPlugin(options) {
             // (script_name pointing at the sidecar) so platform.env.MY_DO and
             // platform.env.MY_WORKFLOW calls in +server.ts reach the sidecar via
             // the wrangler dev registry.
-            const proxyConfig = parseJsonc(rawJson);
-            if (proxyConfig.durable_objects?.bindings) {
-                proxyConfig.durable_objects.bindings = proxyConfig.durable_objects.bindings.map((b) => b.script_name ? b : { ...b, script_name: sidecarName });
+            const proxyConfig = structuredClone(baseConfig);
+            // Wrangler does not merge per-env `durable_objects`/`workflows`/
+            // `migrations` arrays with the top-level — the selected env wholly
+            // overrides them. So we patch only the scope wrangler will actually
+            // use: top-level when no env, env[envName] when CLOUDFLARE_ENV is set.
+            const activeScope = envName ? proxyConfig.env?.[envName] : proxyConfig;
+            if (envName && !activeScope) {
+                throw new Error(`CLOUDFLARE_ENV="${envName}" but no \`env.${envName}\` block in the wrangler config`);
             }
-            if (Array.isArray(proxyConfig.workflows)) {
-                proxyConfig.workflows = proxyConfig.workflows.map((w) => w.script_name ? w : { ...w, script_name: sidecarName });
+            if (activeScope.durable_objects?.bindings) {
+                activeScope.durable_objects.bindings = activeScope.durable_objects.bindings.map((b) => b.script_name ? b : { ...b, script_name: registeredSidecarName });
             }
-            delete proxyConfig.migrations;
+            if (Array.isArray(activeScope.workflows)) {
+                activeScope.workflows = activeScope.workflows.map((w) => w.script_name ? w : { ...w, script_name: registeredSidecarName });
+            }
+            delete activeScope.migrations;
             proxyConfigPath = resolve('.platform-proxy-wrangler.jsonc');
             await writeFile(proxyConfigPath, JSON.stringify(proxyConfig, null, '\t'));
-            // A third config used only by `wrangler types`. Identical to the dev
-            // config but kept separate so the user can run `wrangler types
-            // --config .types-worker-wrangler.jsonc` to get typed bindings like
-            // DurableObjectNamespace<EchoDO> resolved from the source entry.
-            const typesConfig = parseJsonc(rawJson);
-            typesConfig.name = sidecarName;
-            typesConfig.main = options.entryPoint;
-            typesConfig.dev = { ...typesConfig.dev, port: devPort };
-            delete typesConfig.assets;
-            typesConfigPath = resolve('.types-worker-wrangler.jsonc');
-            await writeFile(typesConfigPath, JSON.stringify(typesConfig, null, '\t'));
             worker = await unstable_startWorker({
                 config: tempConfigPath,
-                dev: { registry: getWranglerRegistryPath() },
+                // `testScheduled` mounts a `/__scheduled` endpoint on the sidecar
+                // so cron handlers can be invoked manually in dev — wrangler dev
+                // never auto-fires crons. Curl
+                // `http://localhost:<devPort>/__scheduled?cron=*+*+*+*+*` to
+                // trigger your `scheduled` handler.
+                dev: { registry: getWranglerRegistryPath(), testScheduled: true },
                 build: {
                     nodejsCompatMode: (parsedConfig) => getNodejsCompatMode(parsedConfig.compatibility_date, parsedConfig.compatibility_flags)
                 }
@@ -219,23 +241,11 @@ async function exists(path) {
     }
 }
 /**
- * Mirrors miniflare's `getNodeCompat` mode resolution. wrangler's
- * `unstable_startWorker` does not derive this from the config flags
- * automatically — without it, wrangler falls back to the legacy nodejs
- * compat plugin and warns about `node:*` imports even when
+ * wrangler's `unstable_startWorker` does not derive this from the config
+ * flags automatically — without it, wrangler falls back to the legacy
+ * nodejs compat plugin and warns about `node:*` imports even when
  * `nodejs_compat` is enabled.
  */
 function getNodejsCompatMode(compatibilityDate, compatibilityFlags = []) {
-    const hasCompat = compatibilityFlags.includes('nodejs_compat');
-    const hasCompatV2 = compatibilityFlags.includes('nodejs_compat_v2');
-    const hasNoCompatV2 = compatibilityFlags.includes('no_nodejs_compat_v2');
-    const hasAls = compatibilityFlags.includes('nodejs_als');
-    const date = compatibilityDate ?? '2000-01-01';
-    if (hasCompatV2 || (hasCompat && date >= '2024-09-23' && !hasNoCompatV2))
-        return 'v2';
-    if (hasCompat)
-        return 'v1';
-    if (hasAls)
-        return 'als';
-    return null;
+    return getNodeCompat(compatibilityDate, [...compatibilityFlags]).mode;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@oselvar/sveltekit-add-worker-exports",
-	"version": "0.3.4",
+	"version": "1.0.0",
 	"description": "Vite plugin that adds Durable Object and Workflow exports to SvelteKit Cloudflare workers",
 	"type": "module",
 	"publishConfig": {
@@ -10,10 +10,6 @@
 		".": {
 			"types": "./dist/index.d.ts",
 			"import": "./dist/index.js"
-		},
-		"./hooks": {
-			"types": "./dist/hooks.d.ts",
-			"import": "./dist/hooks.js"
 		}
 	},
 	"files": [