@oselvar/sveltekit-add-worker-exports 2.1.2 → 2.2.1

package/README.md

@@ -4,6 +4,8 @@ A Vite plugin that makes any class-based Cloudflare Worker export (Durable Objec
 
 Works with **SvelteKit 2 and SvelteKit 3** (see [`example/`](example) and [`example-v3/`](example-v3)).
 
+The examples below use SvelteKit 2's `platform.env`. SvelteKit 3's `adapter-cloudflare` (8.0.0-next.7 and later) no longer provides `event.platform`: read bindings with `import { env } from 'cloudflare:workers'` instead, as [`example-v3/`](example-v3) does. The plugin's dev-registry wiring works the same either way.
+
 **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. 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).
@@ -114,6 +116,16 @@ 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.
 
+### Wrangler environments
+
+Set `CLOUDFLARE_ENV` to run dev against one of the `env` blocks in your wrangler config:
+
+```bash
+CLOUDFLARE_ENV=staging pnpm dev
+```
+
+The sidecar then behaves like `wrangler dev --env staging`: it uses `env.staging`'s bindings and `vars`, loads `.env.staging` / `.env.staging.local` (or `.dev.vars.staging`) on top of `.env` / `.env.local`, and registers as `<name>-dev-worker-staging`. As with wrangler, values in `.env` files override `vars`.
+
 ## 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:
@@ -302,25 +314,29 @@ The plugin reads your wrangler config, creates a temporary config with `main` po
 
 ### Generating typed bindings
 
-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:
+The dev plugin runs the sidecar from a derived `.dev-worker-wrangler.jsonc`: your wrangler config with `main` pointing to your source entry point and `assets` removed. Use it to generate fully generic Cloudflare types:
 
 ```bash
+npx sveltekit-add-worker-exports write-config
 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).
+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 also drags `.svelte-kit/cloudflare/_worker` into `tsc` via `mainModule`).
 
-Add this to your `package.json` scripts for convenience:
+`write-config` writes the same file the dev server does, without starting it. It reads `entryPoint` (and `wranglerConfig`, if set) from the `addWorkerExports()` call in your `vite.config.ts`, so it works in CI. Add scripts to `package.json`:
 
 ```json
 {
   "scripts": {
-    "types": "wrangler types --config .dev-worker-wrangler.jsonc"
+    "types": "sveltekit-add-worker-exports write-config && wrangler types --config .dev-worker-wrangler.jsonc",
+    "types:check": "sveltekit-add-worker-exports write-config && wrangler types --config .dev-worker-wrangler.jsonc --check"
   }
 }
 ```
 
-Note: the `.dev-worker-wrangler.jsonc` file is generated when the dev server starts. Run `pnpm dev` at least once before running `wrangler types`.
+Commit `worker-configuration.d.ts` and run `types:check` in CI to catch stale types. Add `.dev-worker-wrangler.jsonc` to `.gitignore`.
+
+Options: `--out <path>` changes the output file, `--vite-config <path>` points at a non-default vite config, and `--entry <path>` (with optional `--wrangler-config <path>`) skips loading the vite config altogether. From code, use `writeDevWorkerConfig({ entryPoint })` or the pure `deriveDevWorkerConfig(config, { entryPoint })`.
 
 ## Why this exists
 

package/bin/sveltekit-add-worker-exports.js

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+// Committed launcher (not built) so package managers can link the bin
+// before `dist/` exists, e.g. in this workspace right after `pnpm install`.
+import '../dist/bin.js';

package/dist/bin.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/bin.js

@@ -0,0 +1,9 @@
+import { main, USAGE, UsageError } from './cli.js';
+main(process.argv.slice(2)).catch((error) => {
+    const message = error instanceof Error ? error.message : String(error);
+    process.stderr.write(`sveltekit-add-worker-exports: ${message}\n`);
+    if (error instanceof UsageError) {
+        process.stderr.write(`\n${USAGE}`);
+    }
+    process.exitCode = 1;
+});

package/dist/cli.d.ts

@@ -0,0 +1,20 @@
+/**
+ * CLI for tasks that shouldn't require a running `vite dev`.
+ *
+ *   sveltekit-add-worker-exports write-config [options]
+ *
+ * Writes `.dev-worker-wrangler.jsonc` (the config the dev sidecar runs) so
+ * `wrangler types --config .dev-worker-wrangler.jsonc [--check]` works in CI.
+ * The plugin options are read from the vite config by default; `--entry`
+ * skips loading it.
+ */
+import { type AddWorkerExportsOptions } from './index.js';
+export declare const USAGE = "Usage: sveltekit-add-worker-exports write-config [options]\n\nWrites .dev-worker-wrangler.jsonc for `wrangler types --config .dev-worker-wrangler.jsonc`\nwithout starting the dev server.\n\nOptions:\n  --out <path>              Output file (default: .dev-worker-wrangler.jsonc)\n  --vite-config <path>      Vite config to read plugin options from (default: auto-discovered)\n  --entry <path>            Worker entry point; skips loading the vite config\n  --wrangler-config <path>  Wrangler config (default: from the vite config, else auto-discovered)\n  -h, --help                Show this help\n";
+export declare function main(argv: string[]): Promise<void>;
+/**
+ * Loads the vite config and returns the options passed to
+ * `addWorkerExports()`, which the dev plugin exposes as `api.options`.
+ */
+export declare function loadPluginOptions(configFile?: string): Promise<AddWorkerExportsOptions>;
+export declare class UsageError extends Error {
+}

package/dist/cli.js

@@ -0,0 +1,86 @@
+/**
+ * CLI for tasks that shouldn't require a running `vite dev`.
+ *
+ *   sveltekit-add-worker-exports write-config [options]
+ *
+ * Writes `.dev-worker-wrangler.jsonc` (the config the dev sidecar runs) so
+ * `wrangler types --config .dev-worker-wrangler.jsonc [--check]` works in CI.
+ * The plugin options are read from the vite config by default; `--entry`
+ * skips loading it.
+ */
+import { relative } from 'node:path';
+import { parseArgs } from 'node:util';
+import { DEV_WORKER_CONFIG_FILE, writeDevWorkerConfig } from './index.js';
+export const USAGE = `Usage: sveltekit-add-worker-exports write-config [options]
+
+Writes ${DEV_WORKER_CONFIG_FILE} for \`wrangler types --config ${DEV_WORKER_CONFIG_FILE}\`
+without starting the dev server.
+
+Options:
+  --out <path>              Output file (default: ${DEV_WORKER_CONFIG_FILE})
+  --vite-config <path>      Vite config to read plugin options from (default: auto-discovered)
+  --entry <path>            Worker entry point; skips loading the vite config
+  --wrangler-config <path>  Wrangler config (default: from the vite config, else auto-discovered)
+  -h, --help                Show this help
+`;
+export async function main(argv) {
+    const { positionals, values } = parseArgs({
+        args: argv,
+        allowPositionals: true,
+        options: {
+            out: { type: 'string' },
+            'vite-config': { type: 'string' },
+            entry: { type: 'string' },
+            'wrangler-config': { type: 'string' },
+            help: { type: 'boolean', short: 'h' }
+        }
+    });
+    if (values.help) {
+        process.stdout.write(USAGE);
+        return;
+    }
+    if (positionals[0] !== 'write-config' || positionals.length > 1) {
+        throw new UsageError(positionals.length ? `Unknown command: ${positionals.join(' ')}` : 'No command given');
+    }
+    const options = values.entry
+        ? { entryPoint: values.entry }
+        : await loadPluginOptions(values['vite-config']);
+    if (values['wrangler-config']) {
+        options.wranglerConfig = values['wrangler-config'];
+    }
+    const path = await writeDevWorkerConfig(options, values.out);
+    process.stdout.write(`Wrote ${relative(process.cwd(), path) || path}\n`);
+}
+/**
+ * Loads the vite config and returns the options passed to
+ * `addWorkerExports()`, which the dev plugin exposes as `api.options`.
+ */
+export async function loadPluginOptions(configFile) {
+    const { loadConfigFromFile } = await import('vite');
+    const loaded = await loadConfigFromFile({ command: 'serve', mode: 'development' }, configFile, process.cwd(), 'silent');
+    if (!loaded) {
+        throw new Error('No vite config found. Pass --vite-config <path> or --entry <path>.');
+    }
+    const plugins = await flattenPlugins(loaded.config.plugins ?? []);
+    const plugin = plugins.find((p) => p.name === 'add-worker-exports-dev');
+    const options = plugin?.api?.options;
+    if (!options) {
+        throw new Error(`addWorkerExports() not found in ${relative(process.cwd(), loaded.path)}. Pass --entry <path> instead.`);
+    }
+    return { ...options };
+}
+async function flattenPlugins(options) {
+    const plugins = [];
+    for (const option of options) {
+        const resolved = await option;
+        if (Array.isArray(resolved)) {
+            plugins.push(...(await flattenPlugins(resolved)));
+        }
+        else if (resolved) {
+            plugins.push(resolved);
+        }
+    }
+    return plugins;
+}
+export class UsageError extends Error {
+}

package/dist/index.d.ts

@@ -48,6 +48,15 @@ export declare const PLUGIN_ASSETS_IGNORE_ENTRIES: string[];
  * public asset serving, so the listed files stay on disk for wrangler to bundle.
  */
 export declare function mergeAssetsIgnore(existing: string, entries: string[]): string;
+/**
+ * Deletes `name`'s dev-registry entry if nothing is listening on its debug
+ * port. A sidecar that doesn't shut down cleanly (killed, crashed) leaves its
+ * entry behind, and the next sidecar with the same name doesn't replace it:
+ * `platform.env` calls then go to the dead address and fail with "Network
+ * connection lost" until the file is deleted. A live entry (e.g. another
+ * `vite dev` of the same app) is left alone.
+ */
+export declare function removeDeadRegistryEntry(registryPath: string, name: string): Promise<void>;
 export interface AddWorkerExportsOptions {
     /** File that exports Durable Object and/or Workflow classes */
     entryPoint: string;
@@ -107,3 +116,33 @@ export declare function addWorkerExports(options: AddWorkerExportsOptions): Plug
  * new requirement.
  */
 export declare function readModuleRules(options: AddWorkerExportsOptions): Promise<ModuleRule[]>;
+/** Default file name for the derived dev-worker wrangler config. */
+export declare const DEV_WORKER_CONFIG_FILE = ".dev-worker-wrangler.jsonc";
+/**
+ * Reads and parses the raw wrangler config (auto-discovered, or
+ * `wranglerConfig` when set). Returns the unresolved file contents — not
+ * wrangler's normalised config — so derived configs stay close to what the
+ * user wrote.
+ */
+export declare function readWranglerConfig(wranglerConfig?: string): Promise<{
+    path: string;
+    config: any;
+}>;
+/**
+ * Derives the wrangler config the dev sidecar runs from the user's config:
+ * `main` points at the source entry point, the name gets a `-dev-worker`
+ * suffix, the dev port is set, and `assets` is dropped.
+ *
+ * The same config is what `wrangler types` should read: generating from the
+ * user's config (whose `main` is the SvelteKit build output) makes wrangler
+ * emit `mainModule: typeof import(".svelte-kit/cloudflare/_worker")` and
+ * untyped Durable Object bindings.
+ */
+export declare function deriveDevWorkerConfig(baseConfig: any, options: Pick<AddWorkerExportsOptions, 'entryPoint' | 'devPort'>): any;
+/**
+ * Reads the wrangler config, derives the dev-worker config and writes it to
+ * `outPath`. Lets `wrangler types --config .dev-worker-wrangler.jsonc` run
+ * without starting `vite dev` (e.g. in CI, with `--check`). Returns the
+ * absolute path written.
+ */
+export declare function writeDevWorkerConfig(options: AddWorkerExportsOptions, outPath?: string): Promise<string>;

package/dist/index.js

@@ -24,6 +24,7 @@ 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 { connect } from 'node:net';
 import { homedir } from 'node:os';
 import { join, resolve } from 'node:path';
 import { parse as parseJsonc } from 'jsonc-parser';
@@ -92,6 +93,42 @@ function getWranglerRegistryPath() {
     }
     return join(process.env.XDG_CONFIG_HOME ?? join(homedir(), '.config'), '.wrangler', 'registry');
 }
+/**
+ * Deletes `name`'s dev-registry entry if nothing is listening on its debug
+ * port. A sidecar that doesn't shut down cleanly (killed, crashed) leaves its
+ * entry behind, and the next sidecar with the same name doesn't replace it:
+ * `platform.env` calls then go to the dead address and fail with "Network
+ * connection lost" until the file is deleted. A live entry (e.g. another
+ * `vite dev` of the same app) is left alone.
+ */
+export async function removeDeadRegistryEntry(registryPath, name) {
+    const entryPath = join(registryPath, name);
+    let address;
+    try {
+        address = JSON.parse(await readFile(entryPath, 'utf-8')).debugPortAddress;
+    }
+    catch {
+        return; // no entry, or one we can't parse -- leave it to wrangler
+    }
+    if (typeof address === 'string' && (await isListening(address)))
+        return;
+    await unlink(entryPath).catch(() => { });
+}
+function isListening(address, timeoutMs = 1_000) {
+    const separator = address.lastIndexOf(':');
+    const host = address.slice(0, separator);
+    const port = Number(address.slice(separator + 1));
+    return new Promise((resolve) => {
+        const socket = connect({ host, port });
+        const done = (listening) => {
+            socket.destroy();
+            resolve(listening);
+        };
+        socket.setTimeout(timeoutMs, () => done(false));
+        socket.once('connect', () => done(true));
+        socket.once('error', () => done(false));
+    });
+}
 /**
  * Returns two Vite plugins: one for build (patches _worker.js) and one for
  * dev (starts a wrangler dev server for Durable Objects).
@@ -107,7 +144,7 @@ function getWranglerRegistryPath() {
  * ```
  */
 export function addWorkerExports(options) {
-    return [buildPlugin(options), devPlugin(options)];
+    return [buildPlugin(options), ...devPlugins(options)];
 }
 /**
  * Patches the adapter-generated `_worker.js`: bundles the named exports into
@@ -232,118 +269,199 @@ function buildPlugin(options) {
         }
     };
 }
-function devPlugin(options) {
+/** Default file name for the derived dev-worker wrangler config. */
+export const DEV_WORKER_CONFIG_FILE = '.dev-worker-wrangler.jsonc';
+/**
+ * Reads and parses the raw wrangler config (auto-discovered, or
+ * `wranglerConfig` when set). Returns the unresolved file contents — not
+ * wrangler's normalised config — so derived configs stay close to what the
+ * user wrote.
+ */
+export async function readWranglerConfig(wranglerConfig) {
+    // Dynamic import — see readModuleRules for why.
+    const { unstable_readConfig } = await import('wrangler');
+    const parsed = unstable_readConfig(wranglerConfig ? { config: wranglerConfig } : {});
+    const path = parsed.configPath;
+    if (!path) {
+        throw new Error(wranglerConfig
+            ? `Could not read wrangler config at ${wranglerConfig}`
+            : 'No wrangler config (wrangler.jsonc, wrangler.json or wrangler.toml) found');
+    }
+    const contents = await readFile(path, 'utf-8');
+    return { path, config: parseWranglerConfig(path, contents) };
+}
+/**
+ * Derives the wrangler config the dev sidecar runs from the user's config:
+ * `main` points at the source entry point, the name gets a `-dev-worker`
+ * suffix, the dev port is set, and `assets` is dropped.
+ *
+ * The same config is what `wrangler types` should read: generating from the
+ * user's config (whose `main` is the SvelteKit build output) makes wrangler
+ * emit `mainModule: typeof import(".svelte-kit/cloudflare/_worker")` and
+ * untyped Durable Object bindings.
+ */
+export function deriveDevWorkerConfig(baseConfig, options) {
+    const devConfig = structuredClone(baseConfig);
+    devConfig.name = devWorkerName(baseConfig);
+    devConfig.main = options.entryPoint;
+    devConfig.dev = { ...devConfig.dev, port: options.devPort ?? DEFAULT_DEV_PORT };
+    delete devConfig.assets;
+    return devConfig;
+}
+/**
+ * Reads the wrangler config, derives the dev-worker config and writes it to
+ * `outPath`. Lets `wrangler types --config .dev-worker-wrangler.jsonc` run
+ * without starting `vite dev` (e.g. in CI, with `--check`). Returns the
+ * absolute path written.
+ */
+export async function writeDevWorkerConfig(options, outPath = DEV_WORKER_CONFIG_FILE) {
+    const { config } = await readWranglerConfig(options.wranglerConfig);
+    const path = resolve(outPath);
+    await writeFile(path, JSON.stringify(deriveDevWorkerConfig(config, options), null, '\t'));
+    return path;
+}
+function devWorkerName(baseConfig) {
+    return `${baseConfig.name ?? 'sveltekit'}-dev-worker`;
+}
+function devPlugins(options) {
     const devPort = options.devPort ?? DEFAULT_DEV_PORT;
     let worker = null;
     let tempConfigPath = null;
     let proxyConfigPath = null;
-    async function readRawConfig() {
-        // Dynamic import — see readModuleRules for why.
-        const { unstable_readConfig } = await import('wrangler');
-        const parsed = unstable_readConfig(options.wranglerConfig ? { config: options.wranglerConfig } : {});
-        const path = parsed.configPath;
-        const contents = await readFile(path, 'utf-8');
-        return { path, contents };
+    let sidecarName = '';
+    let registeredSidecarName = '';
+    /**
+     * Writes `.dev-worker-wrangler.jsonc` (the sidecar's config) and
+     * `.platform-proxy-wrangler.jsonc` (for adapter-cloudflare's
+     * `getPlatformProxy`).
+     */
+    async function writeConfigs() {
+        const { config: baseConfig } = await readWranglerConfig(options.wranglerConfig);
+        sidecarName = devWorkerName(baseConfig);
+        // 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;
+        registeredSidecarName = envName ? `${sidecarName}-${envName}` : sidecarName;
+        // 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.
+        // Outside of dev, `writeDevWorkerConfig` writes the same file.
+        const devConfig = deriveDevWorkerConfig(baseConfig, options);
+        tempConfigPath = resolve(DEV_WORKER_CONFIG_FILE);
+        await writeFile(tempConfigPath, JSON.stringify(devConfig, null, '\t'));
+        // 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
+        // internal DO and Workflow bindings as cross-worker bindings
+        // (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 = 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 (activeScope.durable_objects?.bindings) {
+            activeScope.durable_objects.bindings = activeScope.durable_objects.bindings.map((b) => b.script_name ? b : { ...b, script_name: registeredSidecarName });
+        }
+        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'));
     }
-    return {
-        name: 'add-worker-exports-dev',
-        apply: 'serve',
-        config() {
-            return {
-                define: {
-                    __DEV_WORKER_PORT__: JSON.stringify(devPort)
-                }
-            };
-        },
-        async configureServer(server) {
-            // Dynamic import — see readModuleRules for why.
-            const { unstable_startWorker } = await import('wrangler');
-            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
-            // 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 = structuredClone(baseConfig);
-            devConfig.name = sidecarName;
-            devConfig.main = options.entryPoint;
-            devConfig.dev = { ...devConfig.dev, port: devPort };
-            delete devConfig.assets;
-            // 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');
-            await writeFile(tempConfigPath, 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
-            // internal DO and Workflow bindings as cross-worker bindings
-            // (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 = 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`);
+    return [
+        // Writes the config files before other plugins' dev-server hooks run.
+        // adapter-cloudflare 8 calls `getPlatformProxy` from its own
+        // `configureServer`, which reads `.platform-proxy-wrangler.jsonc` and
+        // fails on a fresh checkout if we haven't written it yet. Vite awaits
+        // these hooks in order.
+        {
+            name: 'add-worker-exports-dev-config',
+            apply: 'serve',
+            configureServer: {
+                order: 'pre',
+                handler: writeConfigs
             }
-            if (activeScope.durable_objects?.bindings) {
-                activeScope.durable_objects.bindings = activeScope.durable_objects.bindings.map((b) => b.script_name ? b : { ...b, script_name: registeredSidecarName });
-            }
-            if (Array.isArray(activeScope.workflows)) {
-                activeScope.workflows = activeScope.workflows.map((w) => w.script_name ? w : { ...w, script_name: registeredSidecarName });
+        },
+        // Starts the sidecar in normal order, after SvelteKit's hooks. Starting
+        // it earlier makes wrangler reload it when SvelteKit regenerates files
+        // the bundle watches (e.g. the tsconfig chain), dropping in-flight work
+        // such as a just-created Workflow.
+        {
+            name: 'add-worker-exports-dev',
+            apply: 'serve',
+            // Lets the CLI (`sveltekit-add-worker-exports write-config`) find the
+            // plugin options in a loaded vite config.
+            api: { options },
+            config() {
+                return {
+                    define: {
+                        __DEV_WORKER_PORT__: JSON.stringify(devPort)
+                    }
+                };
+            },
+            async configureServer(server) {
+                // Dynamic import — see readModuleRules for why.
+                const { unstable_startWorker } = await import('wrangler');
+                const structuredLogsHandler = options.structuredLogsHandler ?? makeDefaultWorkerLogHandler(sidecarName);
+                const registryPath = getWranglerRegistryPath();
+                await removeDeadRegistryEntry(registryPath, registeredSidecarName);
+                worker = await unstable_startWorker({
+                    config: tempConfigPath,
+                    // Wrangler falls back to CLOUDFLARE_ENV when resolving the
+                    // config (and the sidecar's name), but not when choosing which
+                    // `.env` / `.dev.vars` files to load: without `env`, only `.env`
+                    // and `.env.local` are read, and they override the env's `vars`.
+                    // Passing it adds `.env.<env>` / `.dev.vars.<env>`, matching
+                    // `wrangler dev --env <env>`. See
+                    // https://github.com/oselvar/sveltekit-add-worker-exports/issues/11
+                    env: process.env.CLOUDFLARE_ENV,
+                    // `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.
+                    //
+                    // `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: registryPath,
+                        testScheduled: true,
+                        structuredLogsHandler
+                    },
+                    build: {
+                        nodejsCompatMode: (parsedConfig) => getNodejsCompatMode(parsedConfig.compatibility_date, parsedConfig.compatibility_flags)
+                    }
+                });
+                server.httpServer?.on('close', async () => {
+                    if (worker) {
+                        await worker.dispose();
+                        worker = null;
+                    }
+                    if (tempConfigPath) {
+                        await unlink(tempConfigPath).catch(() => { });
+                    }
+                    if (proxyConfigPath) {
+                        await unlink(proxyConfigPath).catch(() => { });
+                    }
+                });
             }
-            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
-                // 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.
-                //
-                // `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)
-                }
-            });
-            server.httpServer?.on('close', async () => {
-                if (worker) {
-                    await worker.dispose();
-                    worker = null;
-                }
-                if (tempConfigPath) {
-                    await unlink(tempConfigPath).catch(() => { });
-                }
-                if (proxyConfigPath) {
-                    await unlink(proxyConfigPath).catch(() => { });
-                }
-            });
         }
-    };
+    ];
 }
 /**
  * Default handler for sidecar worker logs. Writes each line to stdout (or

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@oselvar/sveltekit-add-worker-exports",
-	"version": "2.1.2",
+	"version": "2.2.1",
 	"description": "Vite plugin that adds Durable Object and Workflow exports to SvelteKit Cloudflare workers",
 	"type": "module",
 	"publishConfig": {
@@ -12,7 +12,11 @@
 			"import": "./dist/index.js"
 		}
 	},
+	"bin": {
+		"sveltekit-add-worker-exports": "./bin/sveltekit-add-worker-exports.js"
+	},
 	"files": [
+		"bin",
 		"dist"
 	],
 	"license": "MIT",
@@ -37,15 +41,15 @@
 	},
 	"devDependencies": {
 		"@release-it/conventional-changelog": "^11.0.1",
-		"@sveltejs/kit": "^2.69.3",
-		"@types/node": "^26.1.1",
-		"esbuild": "^0.28.1",
-		"miniflare": "^4.20260710.0",
+		"@sveltejs/kit": "^2.70.3",
+		"@types/node": "^26.6.2",
+		"esbuild": "^0.28.2",
+		"miniflare": "^4.20260730.0",
 		"release-it": "^20.2.1",
 		"typescript": "^7.0.2",
-		"vite": "^8.1.4",
-		"vitest": "^4.1.10",
-		"wrangler": "^4.111.0"
+		"vite": "^8.3.0",
+		"vitest": "^4.1.11",
+		"wrangler": "^4.136.2"
 	},
 	"scripts": {
 		"build": "tsc",
@@ -64,6 +68,6 @@
 	},
 	"dependencies": {
 		"jsonc-parser": "^3.3.1",
-		"smol-toml": "^1.7.0"
+		"smol-toml": "^1.8.0"
 	}
 }