Skip to content
Cloudflare Docs
Docs DirectoryAPIsSDKs

Changelog

New updates and improvements at Cloudflare.

Subscribe to RSS View RSS feeds
Workers
hero image

  1. Improved React Server Components support in the Cloudflare Vite plugin

    Workers

    The Cloudflare Vite plugin now integrates seamlessly @vitejs/plugin-rsc ↗, the official Vite plugin for React Server Components ↗.

    A childEnvironments option has been added to the plugin config to enable using multiple environments within a single Worker. The parent environment can then import modules from a child environment in order to access a separate module graph. For a typical RSC use case, the plugin might be configured as in the following example:

    vite.config.ts
    export default defineConfig({
      plugins: [
        cloudflare({
          viteEnvironment: {
            name: "rsc",
            childEnvironments: ["ssr"],
          },
        }),
      ],
    });

    @vitejs/plugin-rsc provides the lower level functionality that frameworks, such as React Router ↗, build upon. The GitHub repository includes a basic Cloudflare example ↗.

  1. Agents SDK v0.4.0: Readonly connections, MCP security improvements, x402 v2 migration, and custom MCP OAuth providers

    Agents Workers

    The latest release of the Agents SDK ↗ brings readonly connections, MCP protocol and security improvements, x402 payment protocol v2 migration, and the ability to customize OAuth for MCP server connections.

    Readonly connections

    Agents can now restrict WebSocket clients to read-only access, preventing them from modifying agent state. This is useful for dashboards, spectator views, or any scenario where clients should observe but not mutate.

    New hooks: shouldConnectionBeReadonly, setConnectionReadonly, isConnectionReadonly. Readonly connections block both client-side setState() and mutating @callable() methods, and the readonly flag survives hibernation.

    JavaScript
    class MyAgent extends Agent {
      shouldConnectionBeReadonly(connection) {
        // Make spectators readonly
        return connection.url.includes("spectator");
      }
    }

    Custom MCP OAuth providers

    The new createMcpOAuthProvider method on the Agent class allows subclasses to override the default OAuth provider used when connecting to MCP servers. This enables custom authentication strategies such as pre-registered client credentials or mTLS, beyond the built-in dynamic client registration.

    JavaScript
    class MyAgent extends Agent {
      createMcpOAuthProvider(callbackUrl) {
        return new MyCustomOAuthProvider(this.ctx.storage, this.name, callbackUrl);
      }
    }

    MCP SDK upgrade to 1.26.0

    Upgraded the MCP SDK to 1.26.0 to prevent cross-client response leakage. Stateless MCP Servers should now create a new McpServer instance per request instead of sharing a single instance. A guard is added in this version of the MCP SDK which will prevent connection to a Server instance that has already been connected to a transport. Developers will need to modify their code if they declare their McpServer instance as a global variable.

    MCP OAuth callback URL security fix

    Added callbackPath option to addMcpServer to prevent instance name leakage in MCP OAuth callback URLs. When sendIdentityOnConnect is false, callbackPath is now required — the default callback URL would expose the instance name, undermining the security intent. Also fixes callback request detection to match via the state parameter instead of a loose /callback URL substring check, enabling custom callback paths.

    Deprecate onStateUpdate in favor of onStateChanged

    onStateChanged is a drop-in rename of onStateUpdate (same signature, same behavior). onStateUpdate still works but emits a one-time console warning per class. validateStateChange rejections now propagate a CF_AGENT_STATE_ERROR message back to the client.

    x402 v2 migration

    Migrated the x402 MCP payment integration from the legacy x402 package to @x402/core and @x402/evm v2.

    Breaking changes for x402 users:

    • Peer dependencies changed: replace x402 with @x402/core and @x402/evm
    • PaymentRequirements type now uses v2 fields (e.g. amount instead of maxAmountRequired)
    • X402ClientConfig.account type changed from viem.Account to ClientEvmSigner (structurally compatible with privateKeyToAccount())
    Terminal window
    npm uninstall x402
    npm install @x402/core @x402/evm

    Network identifiers now accept both legacy names and CAIP-2 format:

    TypeScript
    // Legacy name (auto-converted)
    {
      network: "base-sepolia",
    }
    

    // CAIP-2 format (preferred)
    {
      network: "eip155:84532",
    }

    Other x402 changes:

    • X402ClientConfig.network is now optional — the client auto-selects from available payment requirements
    • Server-side lazy initialization: facilitator connection is deferred until the first paid tool invocation
    • Payment tokens support both v2 (PAYMENT-SIGNATURE) and v1 (X-PAYMENT) HTTP headers
    • Added normalizeNetwork export for converting legacy network names to CAIP-2 format
    • Re-exports PaymentRequirements, PaymentRequired, Network, FacilitatorConfig, and ClientEvmSigner from agents/x402

    Other improvements

    • Fix useAgent and AgentClient crashing when using basePath routing
    • CORS handling delegated to partyserver's native support (simpler, more reliable)
    • Client-side onStateUpdateError callback for handling rejected state updates

    Upgrade

    To update to the latest version:

    Terminal window
    npm i agents@latest

  1. Visualize data, share links, and create exports with the new Workers Observability dashboard

    Workers

    The Workers Observability dashboard ↗ has some major updates to make it easier to debug your application's issues and share findings with your team.

    Workers Observability dashboard showing events view with event details and share options

    You can now:

    • Create visualizations — Build charts from your Worker data directly in a Worker's Observability tab
    • Export data as JSON or CSV — Download logs and traces for offline analysis or to share with teammates
    • Share events and traces — Generate direct URLs to specific events, invocations, and traces that open standalone pages with full context
    • Customize table columns — Improved field picker to add, remove, and reorder columns in the events table
    • Expandable event details — Expand events inline to view full details without leaving the table
    • Keyboard shortcuts — Navigate the dashboard with hotkey support
    Workers Observability dashboard showing a P99 CPU time visualization grouped by outcome

    These updates are now live in the Cloudflare dashboard, both in a Worker's Observability tab and in the account-level Observability dashboard for a unified experience. To get started, go to Workers & Pages > select your Worker > Observability.

  1. Visualize your Workflows in the Cloudflare dashboard

    Workflows Workers

    Cloudflare Workflows now automatically generates visual diagrams from your code

    Your Workflow is parsed to provide a visual map of the Workflow structure, allowing you to:

    • Understand how steps connect and execute
    • Visualize loops and nested logic
    • Follow branching paths for conditional logic
    Example diagram

    You can collapse loops and nested logic to see the high-level flow, or expand them to see every step.

    Workflow diagrams are available in beta for all JavaScript and TypeScript Workflows. Find your Workflows in the Cloudflare dashboard ↗ to see their diagrams.

  1. New Placement Hints for Workers

    Workers

    You can now configure Workers to run close to infrastructure in legacy cloud regions to minimize latency to existing services and databases. This is most useful when your Worker makes multiple round trips.

    To set a placement hint, set the placement.region property in your Wrangler configuration file:

    JSONC
    {
      "placement": {
        "region": "aws:us-east-1",
      },
    }

    Placement hints support Amazon Web Services (AWS), Google Cloud Platform (GCP), and Microsoft Azure region identifiers. Workers run in the Cloudflare data center ↗ with the lowest latency to the specified cloud region.

    If your existing infrastructure is not in these cloud providers, expose it to placement probes with placement.host for layer 4 checks or placement.hostname for layer 7 checks. These probes are designed to locate single-homed infrastructure and are not suitable for anycasted or multicasted resources.

    JSONC
    {
      "placement": {
        "host": "my_database_host.com:5432",
      },
    }
    JSONC
    {
      "placement": {
        "hostname": "my_api_server.com",
      },
    }

    This is an extension of Smart Placement, which automatically places your Workers closer to back-end APIs based on measured latency. When you do not know the location of your back-end APIs or have multiple back-end APIs, set mode: "smart":

    JSONC
    {
      "placement": {
        "mode": "smart",
      },
    }

  1. Use auxiliary Workers alongside full-stack frameworks

    Workers

    Auxiliary Workers are now fully supported when using full-stack frameworks, such as React Router and TanStack Start, that integrate with the Cloudflare Vite plugin. They are included alongside the framework's build output in the build output directory. Note that this feature requires Vite 7 or above.

    Auxiliary Workers are additional Workers that can be called via service bindings from your main (entry) Worker. They are defined in the plugin config, as in the example below:

    vite.config.ts
    import { defineConfig } from "vite";
    import { tanstackStart } from "@tanstack/react-start/plugin/vite";
    import { cloudflare } from "@cloudflare/vite-plugin";
    

    export default defineConfig({
      plugins: [
        tanstackStart(),
        cloudflare({
          viteEnvironment: { name: "ssr" },
          auxiliaryWorkers: [{ configPath: "./wrangler.aux.jsonc" }],
        }),
      ],
    });

    See the Vite plugin API docs for more info.

  1. Import SQL files as additional modules by default

    Workers

    The .sql file extension is now automatically configured to be importable in your Worker code when using Wrangler or the Cloudflare Vite plugin. This is particular useful for importing migrations in Durable Objects and means you no longer need to configure custom rules when using Drizzle ↗.

    SQL files are imported as JavaScript strings:

    TypeScript
    // `example` will be a JavaScript string
    import example from "./example.sql";

  1. `wrangler types` now generates types for all environments

    Workers

    The wrangler types command now generates TypeScript types for bindings from all environments defined in your Wrangler configuration file by default.

    Previously, wrangler types only generated types for bindings in the top-level configuration (or a single environment when using the --env flag). This meant that if you had environment-specific bindings — for example, a KV namespace only in production or an R2 bucket only in staging — those bindings would be missing from your generated types, causing TypeScript errors when accessing them.

    Now, running wrangler types collects bindings from all environments and includes them in the generated Env type. This ensures your types are complete regardless of which environment you deploy to.

    Generating types for a specific environment

    If you want the previous behavior of generating types for only a specific environment, you can use the --env flag:

    Terminal window
    wrangler types --env production

    Learn more about generating types for your Worker in the Wrangler documentation.

  1. Validate your generated types with `wrangler types --check`

    Workers

    Wrangler now supports a --check flag for the wrangler types command. This flag validates that your generated types are up to date without writing any changes to disk.

    This is useful in CI/CD pipelines where you want to ensure that developers have regenerated their types after making changes to their Wrangler configuration. If the types are out of date, the command will exit with a non-zero status code.

    Terminal window
    npx wrangler types --check

    If your types are up to date, the command will succeed silently. If they are out of date, you'll see an error message indicating which files need to be regenerated.

    For more information, see the Wrangler types documentation.

  1. Get notified when your Workers builds succeed or fail

    Workers Queues

    You can now receive notifications when your Workers' builds start, succeed, fail, or get cancelled using Event Subscriptions.

    Workers Builds publishes events to a Queue that your Worker can read messages from, and then send notifications wherever you need — Slack, Discord, email, or any webhook endpoint.

    You can deploy this Worker ↗ to your own Cloudflare account to send build notifications to Slack:

    Deploy to Cloudflare

    The template includes:

    • Build status with Preview/Live URLs for successful deployments
    • Inline error messages for failed builds
    • Branch, commit hash, and author name
    Slack notifications showing build events

    For setup instructions, refer to the template README ↗ or the Event Subscriptions documentation.

  1. Shell tab completions for Wrangler CLI

    Workers

    Wrangler now includes built-in shell tab completion support, making it faster and easier to navigate commands without memorizing every option. Press Tab as you type to autocomplete commands, subcommands, flags, and even option values like log levels.

    Tab completions are supported for Bash, Zsh, Fish, and PowerShell.

    Setup

    Generate the completion script for your shell and add it to your configuration file:

    Terminal window
    # Bash
    wrangler complete bash >> ~/.bashrc
    

    # Zsh
    wrangler complete zsh >> ~/.zshrc
    

    # Fish
    wrangler complete fish >> ~/.config/fish/config.fish
    

    # PowerShell
    wrangler complete powershell >> $PROFILE

    After adding the script, restart your terminal or source your configuration file for the changes to take effect. Then you can simply press Tab to see available completions:

    Terminal window
    wrangler d<TAB>          # completes to 'deploy', 'dev', 'd1', etc.
    wrangler kv <TAB>        # shows subcommands: namespace, key, bulk

    Tab completions are dynamically generated from Wrangler's command registry, so they stay up-to-date as new commands and options are added. This feature is powered by @bomb.sh/tab ↗.

    See the wrangler complete documentation for more details.

  1. Workers Analytics Engine SQL now supports filtering using HAVING and LIKE

    Workers Analytics Engine Workers

    You can now use the HAVING clause and LIKE pattern matching operators in Workers Analytics Engine ↗.

    Workers Analytics Engine allows you to ingest and store high-cardinality data at scale and query your data through a simple SQL API.

    Filtering using HAVING

    The HAVING clause complements the WHERE clause by enabling you to filter groups based on aggregate values. While WHERE filters rows before aggregation, HAVING filters groups after aggregation is complete.

    You can use HAVING to filter groups where the average exceeds a threshold:

    SELECT
        blob1 AS probe_name,
        avg(double1) AS average_temp
    FROM temperature_readings
    GROUP BY probe_name
    HAVING average_temp > 10

    You can also filter groups based on aggregates such as the number of items in the group:

    SELECT
        blob1 AS probe_name,
        count() AS num_readings
    FROM temperature_readings
    GROUP BY probe_name
    HAVING num_readings > 100

    Pattern matching using LIKE

    The new pattern matching operators enable you to search for strings that match specific patterns using wildcard characters:

    • LIKE - case-sensitive pattern matching
    • NOT LIKE - case-sensitive pattern exclusion
    • ILIKE - case-insensitive pattern matching
    • NOT ILIKE - case-insensitive pattern exclusion

    Pattern matching supports two wildcard characters: % (matches zero or more characters) and _ (matches exactly one character).

    You can match strings starting with a prefix:

    SELECT *
    FROM logs
    WHERE blob1 LIKE 'error%'

    You can also match file extensions (case-insensitive):

    SELECT *
    FROM requests
    WHERE blob2 ILIKE '%.jpg'

    Another example is excluding strings containing specific text:

    SELECT *
    FROM events
    WHERE blob3 NOT ILIKE '%debug%'

    Ready to get started?

    Learn more about the HAVING clause or pattern matching operators in the Workers Analytics Engine SQL reference documentation.

  1. Build microfrontend applications on Workers

    Workers

    You can now deploy microfrontends to Cloudflare, splitting a single application into smaller, independently deployable units that render as one cohesive application. This lets different teams using different frameworks develop, test, and deploy each microfrontend without coordinating releases.

    Microfrontends solve several challenges for large-scale applications:

    • Independent deployments: Teams deploy updates on their own schedule without redeploying the entire application
    • Framework flexibility: Build multi-framework applications (for example, Astro, Remix, and Next.js in one app)
    • Gradual migration: Migrate from a monolith to a distributed architecture incrementally

    Create a microfrontend project:

    Deploy to Cloudflare

    This template automatically creates a router worker with pre-configured routing logic, and lets you configure Service bindings to Workers you have already deployed to your Cloudflare account. The router Worker analyzes incoming requests, matches them against configured routes, and forwards requests to the appropriate microfrontend via service bindings. The router automatically rewrites HTML, CSS, and headers to ensure assets load correctly from each microfrontend's mount path. The router includes advanced features like preloading for faster navigation between microfrontends, smooth page transitions using the View Transitions API, and automatic path rewriting for assets, redirects, and cookies.

    Each microfrontend can be a full-framework application, a static site with Workers Static Assets, or any other Worker-based application.

    Get started with the microfrontends template ↗, or read the microfrontends documentation for implementation details.

  1. Agents SDK v0.3.0, workers-ai-provider v3.0.0, and ai-gateway-provider v3.0.0 with AI SDK v6 support

    Agents Workers

    We've shipped a new release for the Agents SDK ↗ v0.3.0 bringing full compatibility with AI SDK v6 ↗ and introducing the unified tool pattern, dynamic tool approval, and enhanced React hooks with improved tool handling.

    This release includes improved streaming and tool support, dynamic tool approval (for "human in the loop" systems), enhanced React hooks with onToolCall callback, improved error handling for streaming responses, and seamless migration from v5 patterns.

    This makes it ideal for building production AI chat interfaces with Cloudflare Workers AI models, agent workflows, human-in-the-loop systems, or any application requiring reliable tool execution and approval workflows.

    Additionally, we've updated workers-ai-provider v3.0.0, the official provider for Cloudflare Workers AI models, and ai-gateway-provider v3.0.0, the provider for Cloudflare AI Gateway, to be compatible with AI SDK v6.

    Agents SDK v0.3.0

    Unified Tool Pattern

    AI SDK v6 introduces a unified tool pattern where all tools are defined on the server using the tool() function. This replaces the previous client-side AITool pattern.

    Server-Side Tool Definition

    TypeScript
    import { tool } from "ai";
    import { z } from "zod";
    

    // Server: Define ALL tools on the server
    const tools = {
      // Server-executed tool
      getWeather: tool({
        description: "Get weather for a city",
        inputSchema: z.object({ city: z.string() }),
        execute: async ({ city }) => fetchWeather(city)
      }),
    

      // Client-executed tool (no execute = client handles via onToolCall)
      getLocation: tool({
        description: "Get user location from browser",
        inputSchema: z.object({})
        // No execute function
      }),
    

      // Tool requiring approval (dynamic based on input)
      processPayment: tool({
        description: "Process a payment",
        inputSchema: z.object({ amount: z.number() }),
        needsApproval: async ({ amount }) => amount > 100,
        execute: async ({ amount }) => charge(amount)
      })
    };

    Client-Side Tool Handling

    TypeScript
    // Client: Handle client-side tools via onToolCall callback
    import { useAgentChat } from "agents/ai-react";
    

    const { messages, sendMessage, addToolOutput } = useAgentChat({
      agent,
      onToolCall: async ({ toolCall, addToolOutput }) => {
        if (toolCall.toolName === "getLocation") {
          const position = await new Promise((resolve, reject) => {
            navigator.geolocation.getCurrentPosition(resolve, reject);
          });
          addToolOutput({
            toolCallId: toolCall.toolCallId,
            output: {
              lat: position.coords.latitude,
              lng: position.coords.longitude
            }
          });
        }
      }
    });

    Key benefits of the unified tool pattern:

    • Server-defined tools: All tools are defined in one place on the server
    • Dynamic approval: Use needsApproval to conditionally require user confirmation
    • Cleaner client code: Use onToolCall callback instead of managing tool configs
    • Type safety: Full TypeScript support with proper tool typing

    useAgentChat(options)

    Creates a new chat interface with enhanced v6 capabilities.

    TypeScript
    // Basic chat setup with onToolCall
    const { messages, sendMessage, addToolOutput } = useAgentChat({
      agent,
      onToolCall: async ({ toolCall, addToolOutput }) => {
        // Handle client-side tool execution
        await addToolOutput({
          toolCallId: toolCall.toolCallId,
          output: { result: "success" }
        });
      }
    });

    Dynamic Tool Approval

    Use needsApproval on server tools to conditionally require user confirmation:

    TypeScript
    const paymentTool = tool({
      description: "Process a payment",
      inputSchema: z.object({
        amount: z.number(),
        recipient: z.string()
      }),
      needsApproval: async ({ amount }) => amount > 1000,
      execute: async ({ amount, recipient }) => {
        return await processPayment(amount, recipient);
      }
    });

    Tool Confirmation Detection

    The isToolUIPart and getToolName functions now check both static and dynamic tool parts:

    TypeScript
    import { isToolUIPart, getToolName } from "ai";
    

    const pendingToolCallConfirmation = messages.some((m) =>
      m.parts?.some(
        (part) => isToolUIPart(part) && part.state === "input-available",
      ),
    );
    

    // Handle tool confirmation
    if (pendingToolCallConfirmation) {
      await addToolOutput({
        toolCallId: part.toolCallId,
        output: "User approved the action"
      });
    }

    If you need the v5 behavior (static-only checks), use the new functions:

    TypeScript
    import { isStaticToolUIPart, getStaticToolName } from "ai";

    convertToModelMessages() is now async

    The convertToModelMessages() function is now asynchronous. Update all calls to await the result:

    TypeScript
    import { convertToModelMessages } from "ai";
    

    const result = streamText({
      messages: await convertToModelMessages(this.messages),
      model: openai("gpt-4o")
    });

    ModelMessage type

    The CoreMessage type has been removed. Use ModelMessage instead:

    TypeScript
    import { convertToModelMessages, type ModelMessage } from "ai";
    

    const modelMessages: ModelMessage[] = await convertToModelMessages(messages);

    generateObject mode option removed

    The mode option for generateObject has been removed:

    TypeScript
    // Before (v5)
    const result = await generateObject({
      mode: "json",
      model,
      schema,
      prompt
    });
    

    // After (v6)
    const result = await generateObject({
      model,
      schema,
      prompt
    });

    Structured Output with generateText

    While generateObject and streamObject are still functional, the recommended approach is to use generateText/streamText with the Output.object() helper:

    TypeScript
    import { generateText, Output, stepCountIs } from "ai";
    

    const { output } = await generateText({
      model: openai("gpt-4"),
      output: Output.object({
        schema: z.object({ name: z.string() })
      }),
      stopWhen: stepCountIs(2),
      prompt: "Generate a name"
    });

    Note: When using structured output with generateText, you must configure multiple steps with stopWhen because generating the structured output is itself a step.

    workers-ai-provider v3.0.0

    Seamless integration with Cloudflare Workers AI models through the updated workers-ai-provider v3.0.0 with AI SDK v6 support.

    Model Setup with Workers AI

    Use Cloudflare Workers AI models directly in your agent workflows:

    TypeScript
    import { createWorkersAI } from "workers-ai-provider";
    import { useAgentChat } from "agents/ai-react";
    

    // Create Workers AI model (v3.0.0 - enhanced v6 internals)
    const model = createWorkersAI({
      binding: env.AI,
    })("@cf/meta/llama-3.2-3b-instruct");

    Enhanced File and Image Support

    Workers AI models now support v6 file handling with automatic conversion:

    TypeScript
    // Send images and files to Workers AI models
    sendMessage({
      role: "user",
      parts: [
        { type: "text", text: "Analyze this image:" },
        {
          type: "file",
          data: imageBuffer,
          mediaType: "image/jpeg",
        },
      ],
    });
    

    // Workers AI provider automatically converts to proper format

    Streaming with Workers AI

    Enhanced streaming support with automatic warning detection:

    TypeScript
    // Streaming with Workers AI models
    const result = await streamText({
      model: createWorkersAI({ binding: env.AI })("@cf/meta/llama-3.2-3b-instruct"),
      messages: await convertToModelMessages(messages),
      onChunk: (chunk) => {
        // Enhanced streaming with warning handling
        console.log(chunk);
      },
    });

    ai-gateway-provider v3.0.0

    The ai-gateway-provider v3.0.0 now supports AI SDK v6, enabling you to use Cloudflare AI Gateway with multiple AI providers including Anthropic, Azure, AWS Bedrock, Google Vertex, and Perplexity.

    AI Gateway Setup

    Use Cloudflare AI Gateway to add analytics, caching, and rate limiting to your AI applications:

    TypeScript
    import { createAIGateway } from "ai-gateway-provider";
    

    // Create AI Gateway provider (v3.0.0 - enhanced v6 internals)
    const model = createAIGateway({
      gatewayUrl: "https://gateway.ai.cloudflare.com/v1/your-account-id/gateway",
      headers: {
        "Authorization": `Bearer ${env.AI_GATEWAY_TOKEN}`
      }
    })({
      provider: "openai",
      model: "gpt-4o"
    });

    Migration from v5

    Deprecated APIs

    The following APIs are deprecated in favor of the unified tool pattern:

    DeprecatedReplacement
    AITool typeUse AI SDK's tool() function on server
    extractClientToolSchemas()Define tools on server, no client schemas needed
    createToolsFromClientSchemas()Define tools on server with tool()
    toolsRequiringConfirmation optionUse needsApproval on server tools
    experimental_automaticToolResolutionUse onToolCall callback
    tools option in useAgentChatUse onToolCall for client-side execution
    addToolResult()Use addToolOutput()

    Breaking Changes Summary

    1. Unified Tool Pattern: All tools must be defined on the server using tool()
    2. convertToModelMessages() is async: Add await to all calls
    3. CoreMessage removed: Use ModelMessage instead
    4. generateObject mode removed: Remove mode option
    5. isToolUIPart behavior changed: Now checks both static and dynamic tool parts

    Installation

    Update your dependencies to use the latest versions:

    Terminal window
    npm install agents@^0.3.0 workers-ai-provider@^3.0.0 ai-gateway-provider@^3.0.0 ai@^6.0.0 @ai-sdk/react@^3.0.0 @ai-sdk/openai@^3.0.0

    Resources

    Feedback Welcome

    We'd love your feedback! We're particularly interested in feedback on:

    • Migration experience - How smooth was the upgrade from v5 to v6?
    • Unified tool pattern - How does the new server-defined tool pattern work for you?
    • Dynamic tool approval - Does the needsApproval feature meet your needs?
    • AI Gateway integration - How well does the new provider work with your setup?

  1. Static prerendering support for TanStack Start

    Workers

    TanStack Start ↗ apps can now prerender routes to static HTML at build time with access to build time environment variables and bindings, and serve them as static assets. To enable prerendering, configure the prerender option of the TanStack Start plugin in your Vite config:

    vite.config.ts
    import { defineConfig } from "vite";
    import { cloudflare } from "@cloudflare/vite-plugin";
    import { tanstackStart } from "@tanstack/react-start/plugin/vite";
    

    export default defineConfig({
      plugins: [
        cloudflare({ viteEnvironment: { name: "ssr" } }),
        tanstackStart({
          prerender: {
            enabled: true,
          },
        }),
      ],
    });

    This feature requires @tanstack/react-start v1.138.0 or later. See the TanStack Start framework guide for more details.

  1. Build image policies for Workers Builds and Cloudflare Pages

    Workers

    We've published build image policies for Workers Builds and Cloudflare Pages, which establish:

    • Minor version updates: We typically update preinstalled software to the latest available minor version without notice. For tools that don't follow semantic versioning (e.g., Bun or Hugo), we provide 3 months’ notice.
    • Major version updates: Before preinstalled software reaches end-of-life, we update to the next stable LTS version with 3 months’ notice.
    • Build image version deprecation (Pages only): We provide 6 months’ notice before deprecation. Projects on v1 or v2 will be automatically moved to v3 on their specified deprecation dates.

    To prepare for updates, monitor the Cloudflare Changelog ↗, dashboard notifications, and email. You can also override default versions to maintain specific versions.

  1. Retrieve your authentication token with `wrangler auth token`

    Workers

    Wrangler now includes a new wrangler auth token command that retrieves your current authentication token or credentials for use with other tools and scripts.

    Terminal window
    wrangler auth token

    The command returns whichever authentication method is currently configured, in priority order: API token from CLOUDFLARE_API_TOKEN, or OAuth token from wrangler login (automatically refreshed if expired).

    Use the --json flag to get structured output including the token type:

    Terminal window
    wrangler auth token --json

    The JSON output includes the authentication type:

    JSONC
    // API token
    { "type": "api_token", "token": "..." }
    

    // OAuth token
    { "type": "oauth", "token": "..." }
    

    // API key/email (only available with --json)
    { "type": "api_key", "key": "...", "email": "..." }

    API key/email credentials from CLOUDFLARE_API_KEY and CLOUDFLARE_EMAIL require the --json flag since this method uses two values instead of a single token.

  1. Support for ctx.exports in @cloudflare/vitest-pool-workers

    Workers

    The @cloudflare/vitest-pool-workers package now supports the ctx.exports API, allowing you to access your Worker's top-level exports during tests.

    You can access ctx.exports in unit tests by calling createExecutionContext():

    TypeScript
    import { createExecutionContext } from "cloudflare:test";
    import { it, expect } from "vitest";
    

    it("can access ctx.exports", async () => {
      const ctx = createExecutionContext();
      const result = await ctx.exports.MyEntryPoint.myMethod();
      expect(result).toBe("expected value");
    });

    Alternatively, you can import exports directly from cloudflare:workers:

    TypeScript
    import { exports } from "cloudflare:workers";
    import { it, expect } from "vitest";
    

    it("can access imported exports", async () => {
      const result = await exports.MyEntryPoint.myMethod();
      expect(result).toBe("expected value");
    });

    See the context-exports fixture ↗ for a complete example.

  1. Configure your framework for Cloudflare automatically

    Workers

    Wrangler now supports automatic configuration for popular web frameworks in experimental mode, making it even easier to deploy to Cloudflare Workers.

    Previously, if you wanted to deploy an application using a popular web framework like Next.js or Astro, you had to follow tutorials to set up your application for deployment to Cloudflare Workers. This usually involved creating a Wrangler file, installing adapters, or changing configuration options.

    Now wrangler deploy does this for you. Starting with Wrangler 4.55, you can use npx wrangler deploy --x-autoconfig in the directory of any web application using one of the supported frameworks. Wrangler will then proceed to configure and deploy it to your Cloudflare account.

    You can also configure your application without deploying it by using the new npx wrangler setup command. This enables you to easily review what changes we are making so your application is ready for Cloudflare Workers.

    The following application frameworks are supported starting today:

    • Next.js
    • Astro
    • Nuxt
    • TanStack Start
    • SolidStart
    • React Router
    • SvelteKit
    • Docusaurus
    • Qwik
    • Analog

    Automatic configuration also supports static sites by detecting the assets directory and build command. From a single index.html file to the output of a generator like Jekyll or Hugo, you can just run npx wrangler deploy --x-autoconfig to upload to Cloudflare.

    We're really excited to bring you automatic configuration so you can do more with Workers. Please let us know if you run into challenges using this experimentally. We’ve opened a GitHub discussion ↗ and would love to hear your feedback.

  1. New Best Practices guide for Durable Objects

    Durable Objects Workers

    A new Rules of Durable Objects guide is now available, providing opinionated best practices for building effective Durable Objects applications. This guide covers design patterns, storage strategies, concurrency, and common anti-patterns to avoid.

    Key guidance includes:

    • Design around your "atom" of coordination — Create one Durable Object per logical unit (chat room, game session, user) instead of a global singleton that becomes a bottleneck.
    • Use SQLite storage with RPC methods — SQLite-backed Durable Objects with typed RPC methods provide the best developer experience and performance.
    • Understand input and output gates — Learn how Cloudflare's runtime prevents data races by default, how write coalescing works, and when to use blockConcurrencyWhile().
    • Leverage Hibernatable WebSockets — Reduce costs for real-time applications by allowing Durable Objects to sleep while maintaining WebSocket connections.

    The testing documentation has also been updated with modern patterns using @cloudflare/vitest-pool-workers, including examples for testing SQLite storage, alarms, and direct instance access:

    test/counter.test.js
    import { env, runDurableObjectAlarm } from "cloudflare:test";
    import { it, expect } from "vitest";
    

    it("can test Durable Objects with isolated storage", async () => {
      const stub = env.COUNTER.getByName("test");
    

      // Call RPC methods directly on the stub
      await stub.increment();
      expect(await stub.getCount()).toBe(1);
    

      // Trigger alarms immediately without waiting
      await runDurableObjectAlarm(stub);
    });

  1. Billing for SQLite Storage

    Durable Objects Workers

    Storage billing for SQLite-backed Durable Objects will be enabled in January 2026, with a target date of January 7, 2026 (no earlier).

    To view your SQLite storage usage, go to the Durable Objects page

    Go to Durable Objects

    If you do not want to incur costs, please take action such as optimizing queries or deleting unnecessary stored data in order to reduce your SQLite storage usage ahead of the January 7th target. Only usage on and after the billing target date will incur charges.

    Developers on the Workers Paid plan with Durable Object's SQLite storage usage beyond included limits will incur charges according to SQLite storage pricing announced in September 2024 with the public beta ↗. Developers on the Workers Free plan will not be charged.

    Compute billing for SQLite-backed Durable Objects has been enabled since the initial public beta. SQLite-backed Durable Objects currently incur charges for requests and duration, and no changes are being made to compute billing.

    For more information about SQLite storage pricing and limits, refer to the Durable Objects pricing documentation.

  1. Python cold start improvements

    Workers

    Python Workers now feature improved cold start performance, reducing initialization time for new Worker instances. This improvement is particularly noticeable for Workers with larger dependency sets or complex initialization logic.

    Every time you deploy a Python Worker, a memory snapshot is captured after the top level of the Worker is executed. This snapshot captures all imports, including package imports that are often costly to load. The memory snapshot is loaded when the Worker is first started, avoiding the need to reload the Python runtime and all dependencies on each cold start.

    We set up a benchmark that imports common packages (httpx ↗, fastapi ↗ and pydantic ↗) to see how Python Workers stack up against other platforms:

    PlatformMean Cold Start (ms)
    Cloudflare Python Workers1027
    AWS Lambda2502
    Google Cloud Run3069

    These benchmarks run continuously. You can view the results and the methodology on our benchmark page ↗.

    In additional testing, we have found that without any memory snapshot, the cold start for this benchmark takes around 10 seconds, so this change improves cold start performance by roughly a factor of 10.

    To get started with Python Workers, check out our Python Workers overview.

  1. Easy Python package management with Pywrangler

    Workers

    We are introducing a brand new tool called Pywrangler, which simplifies package management in Python Workers by automatically installing Workers-compatible Python packages into your project.

    With Pywrangler, you specify your Worker's Python dependencies in your pyproject.toml file:

    TOML
    [project]
    name = "python-beautifulsoup-worker"
    version = "0.1.0"
    description = "A simple Worker using beautifulsoup4"
    requires-python = ">=3.12"
    dependencies = [
        "beautifulsoup4"
    ]
    

    [dependency-groups]
    dev = [
      "workers-py",
      "workers-runtime-sdk"
    ]

    You can then develop and deploy your Worker using the following commands:

    Terminal window
    uv run pywrangler dev
    uv run pywrangler deploy

    Pywrangler automatically downloads and vendors the necessary packages for your Worker, and these packages are bundled with the Worker when you deploy.

    Consult the Python packages documentation for full details on Pywrangler and Python package management in Workers.

  1. Wrangler config is optional when using Vite plugin

    Workers

    When using the Cloudflare Vite plugin to build and deploy Workers, a Wrangler configuration file is now optional for assets-only (static) sites. If no wrangler.toml, wrangler.json, or wrangler.jsonc file is found, the plugin generates sensible defaults for an assets-only site. The name is based on the package.json or the project directory name, and the compatibility_date uses the latest date supported by your installed Miniflare version.

    This allows easier setup for static sites using Vite. Note that SPAs will still need to set assets.not_found_handling to single-page-application ↗ in order to function correctly.

  1. Configure Workers programmatically using the Vite plugin

    Workers

    The Cloudflare Vite plugin now supports programmatic configuration of Workers without a Wrangler configuration file. You can use the config option to define Worker settings directly in your Vite configuration, or to modify existing configuration loaded from a Wrangler config file. This is particularly useful when integrating with other build tools or frameworks, as it allows them to control Worker configuration without needing users to manage a separate config file.

    The config option

    The Vite plugin's new config option accepts either a partial configuration object or a function that receives the current configuration and returns overrides. This option is applied after any config file is loaded, allowing the plugin to override specific values or define Worker configuration entirely in code.

    Example usage

    Setting config to an object to provide configuration values that merge with defaults and config file settings:

    vite.config.ts
    import { defineConfig } from "vite";
    import { cloudflare } from "@cloudflare/vite-plugin";
    

    export default defineConfig({
      plugins: [
        cloudflare({
          config: {
            name: "my-worker",
            compatibility_flags: ["nodejs_compat"],
            send_email: [
              {
                name: "EMAIL",
              },
            ],
          },
        }),
      ],
    });

    Use a function to modify the existing configuration:

    vite.config.ts
    import { defineConfig } from "vite";
    import { cloudflare } from "@cloudflare/vite-plugin";
    export default defineConfig({
      plugins: [
        cloudflare({
          config: (userConfig) => {
            delete userConfig.compatibility_flags;
          },
        }),
      ],
    });

    Return an object with values to merge:

    vite.config.ts
    import { defineConfig } from "vite";
    import { cloudflare } from "@cloudflare/vite-plugin";
    

    export default defineConfig({
      plugins: [
        cloudflare({
          config: (userConfig) => {
            if (!userConfig.compatibility_flags.includes("no_nodejs_compat")) {
              return { compatibility_flags: ["nodejs_compat"] };
            }
          },
        }),
      ],
    });

    Auxiliary Workers

    Auxiliary Workers also support the config option, enabling multi-Worker architectures without config files.

    Define auxiliary Workers without config files using config inside the auxiliaryWorkers array:

    vite.config.ts
    import { defineConfig } from "vite";
    import { cloudflare } from "@cloudflare/vite-plugin";
    

    export default defineConfig({
      plugins: [
        cloudflare({
          config: {
            name: "entry-worker",
            main: "./src/entry.ts",
            services: [{ binding: "API", service: "api-worker" }],
          },
          auxiliaryWorkers: [
            {
              config: {
                name: "api-worker",
                main: "./src/api.ts",
              },
            },
          ],
        }),
      ],
    });

    For more details and examples, see Programmatic configuration.

Search all changelog entries