v1.16.0-durable-objects-rc.0

Changelog

• Custom Builds - Custom Builds have been stabilized as part of 1.16.0. As part of this, we changed the configuration format to reduce confusion about what fields apply when using "service-worker" vs "modules", and to reduce confusion about how we use the "main" and "module" keys in package.json. The new [build] section is documented here

Installation

npm (recommended)

npm install -g @cloudflare/wrangler@beta

from source

git clone https://github.com/cloudflare/wrangler.git
cd wrangler
git checkout durable-objects-rc
cargo install --path . --debug

Overview

Howdy y'all, we just published candidate release 0 for Durable Objects! This is a continuation of the Custom Builds RC, but renamed to the Durable Objects RC as custom builds have been stabilized.

Durable Objects

Wrangler now supports Durable Objects! We've introduced a new configuration section [durable_objects] that allows you to configure which Durable Objects your project can call into using bindings.

Because Durable Objects are written using modules, you must use custom builds for Durable Objects projects. Templates are provided below.

Accessing Durable Objects

To access Durable Objects, you must configure a binding in wrangler.toml with the class name and script name
whose objects you wish to access using the binding. The script name can be omitted when creating a binding
for a class in the same script.

[durable_objects]
# In rc.1, `bindings` was called `classes`. We'll accept that in rc.2, but in rc.3 and later it will be an error.
bindings = [
  # NOTE: inline tables in TOML must be on a single line
  { name = "COUNTER", class_name = "Counter" }, # Binding to the Counter class in the same script
  { name = "CHAT_ROOM", class_name = "ChatRoom", script_name = "chatroom" } # Binding to the ChatRoom class in a different script
]

The [durable_objects] section has 1 subsection:

• bindings - An array of tables, each table can contain the below fields
  • name - Required, The binding name to use within your worker
  • class_name - Required, The class name you wish to bind to.
  • script_name - Optional, Defaults to the current project's script.

Preparing Durable Objects Classes

When you export a new Durable Objects Class from your script, you must tell the Workers platform about it
before you can create and access Durable Objects associated with that class and script. You can read more about exporting
a new class in the docs.

This process is called a "migration", and is currently performed via extra options on wrangler publish.

To allow creation of Durable Objects associated with an exported class, you'd use --new-class:

wrangler publish --new-class Counter

If you want to rename a Durable Object Class that has already been created, you'd use --rename-class:

WARNING: Make sure to update any bindings to point to the new class name as well!

wrangler publish --rename-class Counter CounterNew

If you want to transfer the Durable Objects associated with a Class in another script to a new Class in this script, you'd use --transfer-class:

WARNING: Make sure to update any bindings to the new script name and class name as well!

wrangler publish --transfer-class counter-script ClassNameInOldScript ClassNameInThisScript

If you want to delete the Durable Objects associated with an exported class, you'd use --delete-class:

WARNING: This will delete all Durable Objects (and their data) associated with the deleted Durable Objects Class!

wrangler publish --delete-class Counter

These are basic examples -- you can use multiple of these options in a single wrangler publish call, one Durable Objects Class per option.

The following example adds 2 new classes (Counter and ChatRoom) and deletes the OldDeprecatedCode class

wrangler publish --new-class Counter --new-class ChatRoom --delete-class OldDeprecatedCode

Durable Objects Templates

We've made 2 templates so you can try out Durable Objects in wrangler:

One uses Rollup to bundle a Worker written using ES Modules, while the other uses Webpack to bundle a worker written as CommonJS modules.

wrangler generate <worker-name> https://github.com/cloudflare/durable-objects-rollup-esm

wrangler generate <worker-name> https://github.com/cloudflare/durable-objects-webpack-commonjs