JavaScript modules come to Cloudflare Workers

Cloudflare Workers now supports the standard JavaScript (ECMAScript) modules system. Until now, Workers written in JavaScript used the Service Worker API format, which was originally designed for attaching script files to web pages as virtual endpoints. That approach worked well with key APIs like fetch() and caches, and it isn't going away: the Service Worker API remains fully supported, part of Cloudflare's commitment to backwards compatibility. No existing code needs to be rewritten.

Modules bring the familiar import and export syntax to Workers, matching what's already available in browsers, Node.js, and Deno. This lets you organize and reuse code across multiple files cleanly, instead of the single-file model of the past.

New event handler syntax

With modules, a Worker is defined via a default export. Instead of calling addEventListener, each handler becomes a function property on that exported module. Currently, Cloudflare supports handlers for fetch, which covers HTTP and WebSocket requests, and scheduled, which handles cron triggers.

The handler signature also changes. Instead of one generic event object, parameters are now spread out:

  • The first parameter is event-specific: a Request for fetch, or a controller containing the cron schedule for scheduled events.
  • The second parameter is an environment object that holds your bindings. Previously these were injected into the global scope, which meant variables could appear "magically." An explicit object is more secure—it lets you control which modules get access to which variables, stopping a problematic third-party library from scanning all your secrets.
  • The third parameter is a context object for registering background tasks via waitUntil(), handy for logging or error reporting that shouldn't block execution.

Durable Objects, which reached general availability this week, map to module exports in a similar way. You can now export a class to define a Durable Object class—for instance, a Counter that responds with an incrementing value.

Beyond JavaScript

Modules aren't just for JavaScript. Cloudflare Workers supports several additional module types, including some not yet standardized:

  • WebAssembly: Previously, WASM was provided as a binding, treated as an external resource. The modules approach imports it directly as code, which is a better fit. While the future proposal for tighter WASM and JavaScript module integration isn't supported yet, the current solution improves ergonomics considerably.
  • Text modules: Import any file as a String, useful for resources like HTML.
  • Binary modules: Import a file as an ArrayBuffer, suitable for assets like images.

Getting started

There are several paths to using modules today. You can try the syntax in the browser-based playground—which doesn't require an account—or in the dashboard's quick editor. The editor auto-detects module usage and lets you switch formats seamlessly. Note that the browser tools currently support creating just one JavaScript module per project; multi-file support there is on the roadmap.

For new projects, the best option is the beta of wrangler 2.0, which was announced recently. Existing projects should stick with wrangler 1.0 (version 1.17 or later) and can enable modules via a wrangler.toml configuration change.

The Cloudflare documentation now includes full details on module syntax. Some examples are still being transitioned, but the docs are being updated to show both the Service Worker API and module formats where relevant, including TypeScript examples.