@cloudflare/vite-plugin

Minor Changes

• Generate source maps for Worker environments by default

  Worker builds now emit source maps unless Vite's build.sourcemap or the Worker's upload_source_maps is set, so deployed Workers get stack traces that point at the original source. The source maps are written next to the Worker bundle and included in Build Output; the client environment is unchanged, so no source maps are added to public assets. Set build.sourcemap: false for the Worker environment, or upload_source_maps: false in the Worker config, to opt out.

Patch Changes

• Fix optional Docker lookups printing Docker CLI errors during successful builds

  cf build looks for Container images left behind by earlier builds so it can remove them. This lookup is best effort, but when Docker could not be reached it still printed errors such as Cannot connect to the Docker daemon, even when the build succeeded and no image needed Docker. Docker commands whose output Wrangler reads no longer forward the Docker CLI's error output to the terminal. If one of these commands fails in a way that stops the command, the error message still includes the Docker CLI's output.

• Use consumer-specific CLI names and commands in shared user-facing messages

  Shared deployment, container, configuration, and authentication helpers can now render commands and configuration filenames for their calling CLI while preserving Wrangler-compatible defaults. This prevents cf workflows from presenting Wrangler-branded guidance when an equivalent cf command exists.

Patch Changes

• Stop the update check from recommending deprecated versions

  Previously, the "update available" notice shown by wrangler and @cloudflare/vite-plugin always pointed at whichever version was tagged latest on npm, even after that version had been deprecated for shipping a bug. Deprecated versions are now never recommended: if the latest release has been deprecated, the newest non-deprecated stable release below it is suggested instead, or nothing at all if you are already on it.

  The check now reads the npm registry directly instead of going through the update-check package, which discarded the deprecation information. The on-disk cache location and one-hour refresh interval are unchanged.

• Ship using and await using declarations to the runtime as written

  Worker builds no longer lower explicit resource management into helper code, so Workers that use it ship about 1.7 KB less. workerd supports the syntax natively. On Vite 8 the plugin builds Workers at an es2026 target, so Oxc leaves the syntax alone. On Vite 6 and 7, where esbuild has no es2026 target, the Worker environments tell esbuild that using is supported instead. Client builds keep their own targets: the plugin changes only the Worker environments.

• Honor the source-map setting in release builds

  Omit the plugin's JavaScript and declaration source maps when building with SOURCEMAPS=false, reducing the installed package size. Normal development builds keep source maps, and application source-map settings are unchanged.

Minor Changes

• Add email-protected Quick Tunnels to the Cloudflare Vite plugin

  Set tunnel.allowedMail to a list of email addresses or domain patterns to require email authentication when exposing a Vite development or preview server through a Quick Tunnel.

Patch Changes

• Resolve the affected Undici dependency in new Wrangler and Vite plugin installs

  Undici 7.29.1 fixes GHSA-3wwx-pv8p-q78v. Update the shared dependency catalog and matching types used by Miniflare and Wrangler so downstream installs can resolve the patched runtime without an application-level override. A published release is still required for consumers; this changeset does not alter already published package metadata.

Minor Changes

• Use cf/config for cloudflare.config.ts authoring

  Experimental cloudflare.config.ts projects must now import defineConfig, bindings, triggers, and related helpers from cf/config. Generated declarations from Wrangler and the Vite plugin also reference this package, so projects using the experimental configuration flow must add cf as a dependency.

  The Vite plugin no longer exports @cloudflare/vite-plugin/experimental-config. wrangler/experimental-config remains available for defineWranglerConfig, but no longer re-exports Cloudflare configuration helpers.

Patch Changes

• Keep dependency optimization caches stable on the first Vite dev server restart.

  The first dev server restart no longer re-optimizes unchanged dependencies, including in projects without Containers. Container images are still cleaned up when the server closes, even after a config reload removes the Cloudflare plugin.

Minor Changes

• Support Workflows declared in exports on ctx.exports in local development

  A Workflow declared in a Worker's exports is now available on ctx.exports in wrangler dev, the Vite plugin and the Vitest plugin, with the same API as a Workflow binding:

  const instance = await ctx.exports.MyWorkflow.create({
    params: { name: "World" },
  });

  ctx.exports and workflows bindings with the same Workflow name share their instances, including instances created before the Workflow was declared in exports. Two Workers can't export the same Workflow name, and a binding to an exported Workflow must refer to the Worker and class that export it. getPlatformProxy() ignores Workflows declared in exports, since it doesn't run the Worker's code.

  wrangler workflows commands run with --local also work with Workflows declared only in exports, without a workflows binding.

  In the Vitest plugin, introspectWorkflow() and introspectWorkflowInstance() still need a Workflow binding, and now explain how to add one when passed a Workflow from ctx.exports. Instances created through ctx.exports are introspected too. A workflows binding whose script_name is the Worker's own name now resolves to the Worker itself again.

Minor Changes

• Advertise Local Explorer scheduled invocations to headless agents

  The Vite plugin's Local Explorer hint now documents how to invoke a Worker's scheduled handler and points agents to the OpenAPI schema for the complete request contract.

Minor Changes

• Allow framework commands to produce Preview Build Output with the experimental config

  When cf previews deploy invokes a framework build command, Preview intent is now preserved. Function-based cloudflare.config.ts files receive isPreview: true, and generated Build Output is marked as a Preview build.

Patch Changes

• Standardize Zod validation error output

  Format validation errors with Zod's built-in prettifyError() helper so Miniflare, Wrangler, the Vite plugin, and the Vitest plugin show consistent messages and property paths.

Minor Changes

• Generate types during development and supported builds with Vite's experimental.newConfig option or Wrangler's --experimental-new-config flag (and --experimental-cf-build-output for builds)

  When Wrangler's --experimental-new-config flag or Vite's experimental.newConfig option is enabled, inferred configuration and runtime declarations are now kept in .cloudflare/types/index.d.ts. Vite refreshes them during development and production builds. Wrangler refreshes them during development and when building with both --experimental-new-config and --experimental-cf-build-output. In the experimental wrangler.config.ts format, the types option is now top-level because it applies to both commands.

Patch Changes

• Prepare the required egress sidecar for local Containers without configured images

  Wrangler dev and Vite dev/preview now pull the required sidecar for Durable Object-managed Containers that select their application image at start time. Previously, these Containers failed to start unless the sidecar image was already cached in Docker.

Minor Changes

• Identify experimental Build Output resource configs by filename and location

  The root remains config.json, Worker configs are now worker.config.json, and Container configs are now container.config.json. Resource configs no longer contain top-level type discriminators, while settings and build context are stored together in the root config.

• Define experimental Cloudflare configuration with a single default export

  Experimental cloudflare.config.ts files now define settings and resources together in a default-exported defineConfig() call. Add a Worker under worker, add Containers to the containers array, or omit both to provide settings only.

  import * as entrypoint from "./src/index.ts" with { type: "cf-worker" };
  
  export default defineConfig({
      accountId: "...",
      complianceRegion: "public",
      worker: {
          name: "my-worker",
          compatibilityDate: "2026-09-18",
          entrypoint,
      },
  });

Patch Changes

• Allow local Container images without exposed ports

  Wrangler and the Cloudflare Vite plugin no longer reject images that omit Docker EXPOSE metadata. Local Containers can run command-only workloads or serve traffic through workerd without declaring an unused image port.

Minor Changes

• Build Containers when emitting experimental Build Output

  Wrangler and the Cloudflare Vite plugin now build Dockerfile-backed Container images when experimental Build Output is enabled. Container configs are emitted under .cloudflare/output/v0/containers with local image references, while existing registry references pass through unchanged.

• Evaluate Flagship flags locally during development

  Flagship bindings now use the local Miniflare store by default in Wrangler and the Vite plugin, keeping development offline and isolated from production flags. Set remote: true on a binding to continue using its remote app.

  Use wrangler flagship flags pull <APP_ID> to seed the store from a remote app. Flag management commands also accept --local to read and update the local store directly.

• Pass Preview intent to defineWorker and upload its resolved configuration

  Preview builds now evaluate programmatic Worker configuration with ctx.isPreview set to true and record that intent in Build Output. The shared Preview uploader deploys the resolved bindings and settings while preserving configured Preview base values when it creates a Preview.

Minor Changes

• Support explicit named Container image selection in local development

  The Vite plugin builds or pulls named images from Wrangler configuration and exposes their local tags through ctx.container.images. Pass one of those references to ctx.container.start({ image }) to select the image.

  This extends the experimental Durable Object-managed Containers interface.

Patch Changes

• Sync Local Explorer endpoint lists across agent hints

  The Local Explorer endpoint list is now consistent across the three places it appears: the AGENTS.md template in create-cloudflare, the runtime agent hint in wrangler dev, and the Vite plugin agent hint. All three now include the observability/clear endpoint, use the canonical /cdn-cgi/local/explorer path, and have cross-reference comments pointing to each other.

• Improve over-limit run_worker_first errors when duplicate rules are present

  The error now reports distinct and duplicate-entry counts and lists duplicated rules, making it clear when removing redundant entries can bring the configuration within the limit.

  Too many `run_worker_first` rules were provided; 105 rules provided (99 distinct, 6 duplicate entries) exceeds max of 100. Note: duplicate entries count towards the route limit. Ensure that no duplicate rules are present in your `run_worker_first` configuration.
  
  The duplicated rules found are:
  - "/rule/0"
  - "/rule/1"
  - "/rule/2"
  - "/rule/3"
  - "/rule/4"
  ...and 1 more duplicated rule.

Patch Changes

• Ignore .wrangler persistence writes in Vite's file watcher

  Miniflare stores local D1, KV, R2, and observability state under .wrangler/state. Those writes were watched as source changes on Linux and Windows, which fired every plugin hotUpdate hook and could make page loads take seconds. The plugin now ignores **/.wrangler/** while preserving any server.watch.ignored patterns already set by the user.

Patch Changes

• Prevent delayed internal errors from fetch-only remote bindings

  Fetch-only remote bindings such as D1 and R2 previously opened an unused WebSocket RPC session. RPC sessions are now created only when an RPC method is called.

Patch Changes

• Preserve HTTP/2 :authority header and non-default port in dev server requests

  When Vite runs over HTTPS with HTTP/2 enabled, browsers send authority via the :authority pseudo-header rather than Host. Previously, pseudo-headers were omitted when creating Fetch requests, causing non-default ports to be dropped from request.url and X-Forwarded-Host. Authority and scheme are now preserved from HTTP/2 pseudo-headers and request properties.

Patch Changes

• Surface Worker export type fetch errors during development

  The Vite plugin now reports the Worker name, HTTP status, and response body when fetching export types fails. This preserves the underlying error instead of replacing it with a JSON parsing error.

Minor Changes

• Enable FUSE-capable local container development

  Miniflare now automatically passes the Docker privileges needed for FUSE to local Durable Object containers when using local rootless Docker on Linux with /dev/fuse available, or a local Docker engine on macOS or through WSL where Linux containers run in a VM. This applies to Wrangler, the Cloudflare Vite plugin, and direct Miniflare use.

• Record the selected mode in the Build Output Specification top-level config.json

  The mode a build was produced in is now written to .cloudflare/output/v0/config.json as a mode field, alongside the account and compliance settings.

Minor Changes

• Allow containers to be attached to a Durable Object from its exports entry

  A container can now be linked to its Durable Object from the export side, using a new container field that names an entry in the containers array. As a result containers.class_name is now optional — a container that is referenced this way only needs a name:

  {
    "name": "my-worker",
    "main": "worker.js",
    "compatibility_date": "2026-07-01",
    "containers": [
      { "name": "my-container", "image": "./Dockerfile", "max_instances": 1 }
    ],
    "exports": {
      "MyContainerDO": {
        "type": "durable-object",
        "storage": "sqlite",
        "container": "my-container"
      }
    }
  }

  The existing containers.class_name direction keeps working and either direction may be used, but the two must agree: a container that names its Durable Object cannot also be claimed by a different one.

  container is only valid on live durable-object exports (created and expecting-transfer) and requires storage: "sqlite". Wrangler now also reports an error when:

  • a container reference names a container that does not exist

  • two Durable Object exports claim the same container

  • a container and a Durable Object export disagree about which one they are linked to

  • a container ends up linked to no Durable Object at all

  • two containers share a name

  • a container's class_name names a Durable Object whose storage is legacy-kv

  • two containers are attached to the same Durable Object

  That last case was previously accepted but could never work: workerd attaches a single container per Durable Object namespace, and in local development every container for a class builds into the same image tag, so one silently overwrote the other. If you have two containers on one class_name, give each its own Durable Object class.

Patch Changes

• Honor access.dev when running Workers with @cloudflare/vite-plugin, so ctx.access.getIdentity() returns the configured identity.

• Handle Worker-side request body cancellation without surfacing stream controller errors in local dev.

• Use a fixed default compatibility date rather than the current date

  When no compatibility date was set, Wrangler, C3 and the Vitest pool all defaulted to the current date. workerd only accepts a compatibility date up to 7 days beyond its own release, so whenever a workerd release was delayed the default could get ahead of the runtime that had been installed, and local development would fail to start.

  The default is now fixed at the release date of the workerd version that ships with each release, which leaves a week of headroom and updates as workerd is upgraded. @cloudflare/vite-plugin previously inlined the date at which it was built. It now shares the same default.

• Prevent date-enabled Node.js compatibility from adding conflicting globals to generated runtime types

  Runtime type generation now treats Node.js compatibility enabled by a compatibility date the same way as an explicit nodejs_compat flag. Node.js globals continue to come from @types/node instead of being generated as any declarations that override those types.

• Use the FedRAMP High managed container registry when Wrangler targets the FedRAMP High compliance region

  Container builds, pushes, deployments, image commands, and local development now select the corresponding production or staging FedRAMP registry and API from either compliance_region or CLOUDFLARE_COMPLIANCE_REGION.

Minor Changes

• Detect Node.js compatibility from the compatibility date, now that nodejs_compat is enabled by default

  As of compatibility date 2026-08-04, workerd enables the nodejs_compat and nodejs_compat_v2 compatibility flags by default. Previously these tools only treated Node.js compatibility as enabled when one of those flags was listed explicitly, so a Worker on a compatibility date of 2026-08-04 or later without the flag would get Node.js APIs from the runtime but no Node.js polyfills from the bundler, and process.env could be substituted with an empty object at build time. They now resolve these flags the same way workerd does, and honour no_nodejs_compat to opt out.

  To keep Node.js compatibility switched off on a newer compatibility date, specify both no_nodejs_compat and no_nodejs_compat_v2, since each flag has its own default.

  @cloudflare/vitest-pool-workers needs nodejs_compat_v2 for its own test runner, so it continues to override a project that opts out of it. On a compatibility date that enables the flag anyway, it now drops the opt-out rather than adding the flag back, which workerd would reject — previously this stopped such a project from running any tests at all.

  wrangler types also no longer attributes its @types/node suggestion to "the nodejs_compat flag", which it can now make for Workers that do not set the flag at all.

Patch Changes

• Ignore a nodejs_compat compatibility flag that the compatibility date already enables

  workerd rejects a compatibility flag that its compatibility date enables by default, so a Worker configured with both a compatibility date of 2026-08-04 or later and nodejs_compat failed to start locally with "The compatibility flag nodejs_compat became the default as of 2026-08-04 so does not need to be specified anymore".

  The redundant nodejs_compat and nodejs_compat_v2 flags are now dropped when starting the runtime, which has no effect on the resulting Worker because the compatibility date enables both anyway. no_nodejs_compat and no_nodejs_compat_v2 still switch Node.js compatibility off, and a flag specified alongside its own opt-out is left alone so that workerd still reports those as contradictory.

Patch Changes

• Update dev and preview for Miniflare's config-based options

  The Vite plugin now converts the Miniflare options it creates for dev and preview sessions to Miniflare's config-based workers shape.

  Users should not expect to notice any changes.

Patch Changes

• Cut the per-request cost of local observability capture

  Every tail event was written to the trace store as its own Durable Object call, so a request paid two or three round-trips per span. On a module-heavy app under the Vite plugin that dominated dev request latency. Rows are now buffered and written in batches, taking a request from roughly thirty calls to three.

  Work in progress still shows up as it happens: the root span is written immediately, console logs and exceptions as they arrive, and a span's completion is written on the next event once 100ms has passed. An invocation that goes completely quiet writes nothing further until it ends, since the flush is driven by tail events rather than a timer.

  The Vite plugin's own router, asset and proxy workers are also no longer captured. Their traces were noise the Observability views already hid, and skipping them cuts the spans recorded per request — a side benefit being that a trace's root is now your Worker rather than __router-worker__.

Minor Changes

• Improve the Local Explorer's Observability views

  console.log messages now render the way the console would (JSON-encoded strings are unwrapped and multi-argument logs are joined), traces and events can be looked up by trace or span id from the search bar, and an event's "View trace" button jumps to the exact invocation that emitted it — even when a trace_id spans several invocations (e.g. a subrequest or self fetch).

• Surface Local Explorer API to headless agents

  When a Vite dev or preview server with the Cloudflare plugin is started in a headless AI agent environment, the plugin now prints the Local Explorer API URL and useful resource routes to stdout so agents can discover and call them programmatically.

Minor Changes

• Enable local observability capture by default in dev

  wrangler dev and the Vite plugin now capture request traces and console logs into the Local Explorer's Observability tab out of the box — previously this was opt-in behind X_LOCAL_OBSERVABILITY=true. Set X_LOCAL_OBSERVABILITY=false to opt out (for example if the extra per-worker collector/streaming-tail services cause trouble in a multi-process dev-registry setup).

Patch Changes

• Rewrite local testing paths (/cdn-cgi/*)

  Miniflare v5 moved its internal local testing endpoints to /cdn-cgi/local/* (and /__cf_local/* for endpoints that must remain reachable over tunnels) to prevent any potential collision with production routes. wrangler dev and the Vite plugin now transparently rewrite the old paths to the new ones, meaning you can continue to use the old paths without issue.

  These are the new paths:

  • /cdn-cgi/handler/scheduled → /cdn-cgi/local/scheduled

  • /cdn-cgi/handler/email → /cdn-cgi/local/email

  • /cdn-cgi/explorer/* → /cdn-cgi/local/explorer/*

  • /cdn-cgi/mf/scheduled → /cdn-cgi/local/scheduled (Note /cdn-cgi/mf/scheduled is already deprecated)

  • /cdn-cgi/mf/stream/* → /__cf_local/stream/*

  • /cdn-cgi/mf/imagedelivery/* → /__cf_local/imagedelivery/*

Minor Changes

• The experimental build output directory now includes the Worker's configuration at .cloudflare/output/v0/workers/default/config.json instead of .cloudflare/output/v0/workers/<worker-name>/worker.config.json

Minor Changes

• Serve the bundled client HTML in dev when Vite's experimental.bundledDev is enabled

  Note that this feature is experimental and subject to change.

Patch Changes

• Destroy the client socket instead of crashing when a WebSocket upgrade fails

  If dispatchFetch rejected while a WebSocket upgrade was still in flight (for example when Miniflare is disposed during a dev server shutdown or restart), the error escaped the async upgrade handler as an unhandled rejection. This could terminate the dev server process and leaked the client socket. The upgrade handler now catches such failures and tears the socket down cleanly.

• Fix compatibility with Vite's experimental.bundledDev option. Keep Miniflare, containers, and tunnels alive when a build runs in dev.

  The plugin used the buildEnd hook as its signal that the dev server was closing, and tore down its dev resources there. Vite's experimental.bundledDev runs a build pass during serve, which fires buildEnd while the dev server is still live — so Miniflare was disposed (the next request failed with Expected \miniflare` to be defined`), locally-built container images were removed, and any active tunnel was closed, all mid-serve.

  During serve, these resources are now torn down from a patched server.close. We will replace server patching with first-class APIs when they are added to Vite.

• Retry transient module-transport failures in the runner worker

  Each fetchModule invoke was a single fetch to the dev server with no retry. If that one fetch failed transiently (e.g. Network connection lost when workerd reuses a loopback connection that Node just closed), Vite's module runner cached the rejection and every request importing the affected module failed for the rest of the dev session. The invoke is an idempotent request for module code, so retry it up to three times before giving up.

Minor Changes

• Add local-dev observability

  wrangler dev and the Vite plugin now capture a trace for every local Worker invocation - spans, logs, and console.* output, including requests that cross worker or Durable Object boundaries.

  You can explore this data two ways:

  • A new Observability tab in the Local Explorer, with a Traces view (recent invocations, an inline timeline waterfall, and filters) and an Events view.

  • A read-only SQL endpoint at /cdn-cgi/explorer/api/local/observability/query, discoverable via the Local Explorer's OpenAPI document, so coding agents and tools can query the same spans and logs tables.

  While this is in testing it's off by default; set X_LOCAL_OBSERVABILITY=true to turn it on. It will be on by default in the public release.

Patch Changes

• Recover local development after the Workers runtime crashes

  Previously, an unexpected workerd crash left Miniflare running but unable to serve subsequent requests. Miniflare now restarts workerd after post-startup crashes, while continuing to surface startup crashes as fatal errors.

  The Cloudflare Vite plugin also restarts the Vite development server after workerd recovers so its environments, hot channels, and module runners are recreated.