Get started
This guide will instruct you through:
- Writing a class that defines a Durable Object.
- Instantiating and communicating with a Durable Object from another Worker via the
Fetch
API. - Deploying a Durable Object.
- Sign up for a Cloudflare account.
- Install
npm
. - Install
Node.js
.
Node.js version manager
1. Enable Durable Objects in the dashboard
To enable Durable Objects, you will need to purchase the Workers Paid plan:
- Log in to the Cloudflare dashboard, and select your account.
- Go to Workers & Pages > Plans.
- Select Purchase Workers Paid and complete the payment process to enable Durable Objects.
2. Create a Worker project
You will access your Durable Object from a Worker. Your Worker application is an interface to interact with your Durable Object.
To create a Worker project, run:
$ npm create cloudflare@latest
$ yarn create cloudflare
Running create cloudflare
will install Wrangler, the Workers CLI. You will use Wrangler to test and deploy your project.
In your terminal, you will be asked a series of questions related to your project:
- Name your new Worker directory by specifying where you want to create your application.
- Select
Co-ordination / multiplayer API (using Durable Objects)
as the type of application you want to create. - Answer
yes
orno
to using TypeScript. - Answer
no
to deploying your Worker.
This will create a new directory, which will include either a src/index.js
or src/index.ts
file to write your code and a wrangler.toml
configuration file.
3. Write a class to define a Durable Object
Before you create and access a Durable Object, its behavior must be defined by an ordinary exported JavaScript class.
Your MyDurableObject
class will have a constructor with two parameters. The first parameter, state
, passed to the class constructor contains state specific to the Durable Object, including methods for accessing storage. The second parameter, env
, contains any bindings you have associated with the Worker when you uploaded it.
index.jsexport class MyDurableObject { constructor(state, env) {}
}
index.tsexport class MyDurableObject { constructor(state: DurableObjectState, env: Env) {}
}
Workers communicate with a Durable Object via the fetch API. Like a Worker, a Durable Object listens for incoming fetch events by registering an event handler. For a Durable Object, the fetch handler is defined as a method on the class.
Your file should now look like:
index.jsexport class MyDurableObject { constructor(state, env) {}
async fetch(request) { return new Response("Hello World"); }
}
index.tsexport class MyDurableObject { constructor(state: DurableObjectState, env: Env) {}
async fetch(request: Request) { return new Response("Hello World"); }
}
A Worker can pass information to a Durable Object via headers, the HTTP method, the Request body, or the Request URI.
4. Instantiate and communicate with a Durable Object
The fetch()
handler allows you to instantiate and communicate to a Durable Object from a Worker.
To communicate with a Durable Object, the fetch handler should look like the following:
index.jsexport default { async fetch(request, env) { let id = env.MY_DURABLE_OBJECT.idFromName(new URL(request.url).pathname);
let stub = env.MY_DURABLE_OBJECT.get(id);
let response = await stub.fetch(request);
return response; },
};
index.tsexport default { async fetch(request, env, ctx): Promise<Response> { let id = env.MY_DURABLE_OBJECT.idFromName(new URL(request.url).pathname);
let stub = env.MY_DURABLE_OBJECT.get(id);
let response = await stub.fetch(request);
return response; },
} satisfies ExportedHandler<Env>;
In the code above, you have:
- Exported your Worker’s main event handlers, such as the
fetch()
handler for receiving HTTP requests. - Passed
env
into thefetch()
handler. Bindings are delivered as a property of the environment object passed as the second parameter when an event handler or class constructor is invoked. By calling theidFromName()
function on the binding, you use a string-derived object ID. You can also ask the system to generate random unique IDs. System-generated unique IDs have better performance characteristics, but require you to store the ID somewhere to access the Object again later. - Derived an object ID from the URL path.
MY_DURABLE_OBJECT.idFromName()
always returns the same ID when given the same string as input (and called on the same class), but never the same ID for two different strings (or for different classes). In this case, you are creating a new object for each unique path. - Constructed the stub for the Durable Object using the ID. A stub is a client object used to send messages to the Durable Object.
- Forwarded the request to the Durable Object.
stub.fetch()
has the same signature as the globalfetch()
function, except that the request is always sent to the object, regardless of the request’s URL. The first time you send a request to a new object, the object will be created for us. If you do not store durable state in the object, it will automatically be deleted later (and recreated if you request it again). If you store durable state, then the object may be evicted from memory but its durable state will be kept permanently. - Received an HTTP response back to the client with
return response
.
Refer to Access a Durable Object from a Worker to learn more about communicating to a Durable Object.
5. Configure Durable Object bindings
Bindings allow your Workers to interact with resources on the Cloudflare developer platform. The Durable Object bindings in your Worker project’s wrangler.toml
will include a binding name (for this guide, use MY_DURABLE_OBJECT
) and the class name (MyDurableObject
).
wrangler.toml[[durable_objects.bindings]]
name = "MY_DURABLE_OBJECT"
class_name = "MyDurableObject"
# or
[durable_objects]
bindings = [ { name = "MY_DURABLE_OBJECT", class_name = "MyDurableObject" }
]
The [[durable_objects.bindings]]
section contains the following 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 environment’s Worker code.
6. Configure Durable Object classes with migrations
A migration is a mapping process from a class name to a runtime state. You perform a migration when creating a new Durable Object class, renaming, deleting and transferring an existing Durable Object class.
Migrations are performed through the [[migrations]]
configurations key in your wrangler.toml
file.
The Durable Object migration to create a new Durable Object class will look like the following in your Worker’s wrangler.toml
file:
wrangler.toml[[migrations]]
tag = "v1" # Should be unique for each entry
new_classes = ["MyDurableObject"] # Array of new classes
Refer to Durable Objects migrations to learn more about the migration process.
7. Develop a Durable Object Worker locally
To test your Durable Object locally, run wrangler dev
:
$ npx wrangler dev
In your console, you should see aHello world
string returned by the Durable Object.
8. Deploy your Durable Object Worker
To deploy your Durable Object Worker:
$ npx wrangler deploy
Once deployed, you should be able to see your newly created Durable Object Worker on the Cloudflare dashboard, Workers & Pages > Overview.
Preview your Durable Object Worker at <YOUR_WORKER>.<YOUR_SUBDOMAIN>.workers.dev
.
By finishing this tutorial, you have successfully created, tested and deployed a Durable Object.
Related resources
- Access a Durable Object from a Worker
- Create Durable Object stubs
- Miniflare - Helpful tools for mocking and testing your Durable Objects.