|
| 1 | +--- |
| 2 | +title: Simpler Workers API that lets you directly manage Workers, Versions, and Deployments |
| 3 | +description: Simpler Workers API, SDK methods, and Terraform resources for directly managing Workers, Versions, and Deployments |
| 4 | +date: 2025-08-11 |
| 5 | +--- |
| 6 | + |
| 7 | +The current Workers script upload API is convenient for a one-shot Workers deploy. However, it unavoidably creates [Versions and Deployments](/workers/configuration/versions-and-deployments/), and sometimes you don't want that to happen. Sometimes, you want more (and simpler!) control over how and when these are created. |
| 8 | + |
| 9 | +In [Cloudflare Terraform Provider](https://registry.terraform.io/providers/cloudflare/cloudflare/5.9.0/docs) 5.9.0 and [cloudflare-typescript](https://github.com/cloudflare/cloudflare-typescript) 4.6.0 (TODO double check these versions), we're introducing a clean, separated API that makes Workers, Versions, and Deployments individual "capital R" resources with clear concerns. It's now possible to create a Worker entity–and reference it elsewhere–before uploading code, bindings, or making it routable from the internet. You'll also enjoy a more ergonomic way to upload modules, fewer total endpoints, and clearer [API docs](/api/resources/workers/). Check out [Infrastructure as Code (IaC)](/workers/platform/infrastructure-as-code) for detailed examples. |
| 10 | + |
| 11 | +## cloudflare-typescript example |
| 12 | + |
| 13 | +```javascript |
| 14 | +const scriptContent = ` |
| 15 | + export default { |
| 16 | + async fetch(request, env, ctx) { |
| 17 | + return new Response(env.MESSAGE, { status: 200 }); |
| 18 | + } |
| 19 | + }; |
| 20 | +`; |
| 21 | + |
| 22 | +/** |
| 23 | + * Create a Worker and set non-versioned settings like observability |
| 24 | + */ |
| 25 | +const worker = await client.workers.create({ |
| 26 | + "my-worker", |
| 27 | + account_id: "...", |
| 28 | + observability: { |
| 29 | + enabled: true, |
| 30 | + }, |
| 31 | +}); |
| 32 | + |
| 33 | +/** |
| 34 | + * Create the first version of the Worker |
| 35 | + * This is where code and bindings are defined and can be different between versions |
| 36 | + */ |
| 37 | +const version = await client.workers.versions.create(worker.id, { |
| 38 | + account_id: "...", |
| 39 | + main_module: "my-worker-script", |
| 40 | + compatibility_date: $today, |
| 41 | + bindings: [ /*...*/ ], |
| 42 | + modules: [ |
| 43 | + { |
| 44 | + name: "my-worker-script", |
| 45 | + content_type: "application/javascript+module", |
| 46 | + content_base64: Buffer.from(scriptContent).toString("base64"), |
| 47 | + }, |
| 48 | + ], |
| 49 | +}); |
| 50 | + |
| 51 | +/** |
| 52 | + * Create a deployment and point all traffic to the version we created |
| 53 | + */ |
| 54 | +const deployment = await client.workers.scripts.deployments.create(worker.name, { |
| 55 | + account_id: "...", |
| 56 | + strategy: "percentage", |
| 57 | + versions: [ |
| 58 | + { |
| 59 | + percentage: 100, |
| 60 | + version_id: version.id, |
| 61 | + }, |
| 62 | + ], |
| 63 | +}); |
| 64 | +``` |
| 65 | + |
| 66 | +## Terraform |
| 67 | + |
| 68 | +In Terraform, you now have the option to just manage the Worker entity. You don't need to manage code, config, or deployments in your plan. This gives you flexibility to use Wrangler for build and deploy—in a different repo—while maintaining presence in your Terraform plan. |
| 69 | + |
| 70 | +```tf |
| 71 | +resource "cloudflare_worker" "my_worker" { |
| 72 | + account_id = "..." |
| 73 | + name = "my-important-service" |
| 74 | +} |
| 75 | +
|
| 76 | +# Manage Versions and Deployments here or outside of Terraform |
| 77 | +# resource "cloudflare_workers_version" "my_worker_version" {} |
| 78 | +# resource "cloudflare_workers_deployment" "my_worker_deployment" {} |
| 79 | +``` |
| 80 | + |
| 81 | +## A radically simpler API |
| 82 | + |
| 83 | +We wanted to make things easier, so we simplified these 8 APIs... |
| 84 | +- /workers/scripts/:script_name |
| 85 | +- /workers/scripts/:script_name/content |
| 86 | +- /workers/scripts/:script_name/script-settings |
| 87 | +- /workers/scripts/:script_name/settings |
| 88 | +- /workers/scripts/:script_name/subdomain |
| 89 | +- /workers/scripts/:script_name/secrets |
| 90 | +- /workers/scripts/:script_name/versions |
| 91 | +- /workers/scripts/:script_name/deployments |
| 92 | + |
| 93 | +Into just three! |
| 94 | +- /workers/workers/:worker_id |
| 95 | +- /workers/workers/:worker_id/versions |
| 96 | +- /workers/scripts/:script_name/deployments |
| 97 | + |
| 98 | +It's not just less endpoints to learn. Can you guess which of the old APIs created a new Version and which didn't? That's no longer a mystery. |
| 99 | + |
| 100 | +For now, the new APIs are in beta and the old ones will remain operational. In the future, we plan to mark the old APIs as deprecated in our OpenAPI docs. |
0 commit comments