Update with newest workers examples

Author: markjmiller

src/content/changelog/workers/2025-08-11-new-workers-api.mdx renamed to src/content/changelog/workers/2025-09-02-new-workers-api.mdx

@@ -1,28 +1,28 @@
 ---
 title: Simpler Workers API that lets you directly manage Workers, Versions, and Deployments
 description: Simpler Workers API, SDK methods, and Terraform resources for directly managing Workers, Versions, and Deployments
-date: 2025-08-11
+date: 2025-09-02
 ---
 
 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.
 
-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.
+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, 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.
 
 ## cloudflare-typescript example
 
 ```javascript
 const scriptContent = `
   export default {
     async fetch(request, env, ctx) {
-      return new Response(env.MESSAGE, { status: 200 });
+      return new Response("Hello, world!", { status: 200 });
     }
   };
 `;
 
 /**
  * Create a Worker and set non-versioned settings like observability
  */
-const worker = await client.workers.create({
+const worker = await client.workers.beta.workers.create({
   "my-worker",
   account_id: "...",
   observability: {
@@ -34,7 +34,7 @@ const worker = await client.workers.create({
  * Create the first version of the Worker
  * This is where code and bindings are defined and can be different between versions
  */
-const version = await client.workers.versions.create(worker.id, {
+const version = await client.workers.beta.workers.versions.create(worker.id, {
   account_id: "...",
   main_module: "my-worker-script",
   compatibility_date: $today,
@@ -65,7 +65,7 @@ const deployment = await client.workers.scripts.deployments.create(worker.name,
 
 ## Terraform
 
-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.
+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 while maintaining presence in your Terraform plan.
 
 ```tf
 resource "cloudflare_worker" "my_worker" {
@@ -81,20 +81,26 @@ resource "cloudflare_worker" "my_worker" {
 ## A radically simpler API
 
 We wanted to make things easier, so we simplified these 8 APIs...
-- /workers/scripts/:script_name
-- /workers/scripts/:script_name/content
-- /workers/scripts/:script_name/script-settings
-- /workers/scripts/:script_name/settings
-- /workers/scripts/:script_name/subdomain
-- /workers/scripts/:script_name/secrets
-- /workers/scripts/:script_name/versions
-- /workers/scripts/:script_name/deployments
+- `/workers/scripts/:script_name`
+- `/workers/scripts/:script_name/content`
+- `/workers/scripts/:script_name/script-settings`
+- `/workers/scripts/:script_name/settings`
+- `/workers/scripts/:script_name/subdomain`
+- `/workers/scripts/:script_name/secrets`
+- `/workers/scripts/:script_name/versions`
+- `/workers/scripts/:script_name/deployments`
 
 Into just three!
-- /workers/workers/:worker_id
-- /workers/workers/:worker_id/versions
-- /workers/scripts/:script_name/deployments
+- `/workers/workers/:worker_id`
+- `/workers/workers/:worker_id/versions`
+- `/workers/scripts/:script_name/deployments`
 
-It's not just fewer endpoints... can you guess which of the old APIs created a new Version and Deployment and which didn't? That's no longer a mystery. POST `/versions` creates a Version and POST `/deployments` creates a Deployment.
+It's not just fewer endpoints... can you guess which of the old APIs created a new Version and Deployment and which didn't? That's no longer a mystery. `/versions` creates Versions and `/deployments` creates Deployments.
 
-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, and remove the old Terraform resources and SDK methods in future major versions.
+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, and remove the old Terraform resources and SDK methods in future major versions.
+
+:::note
+- `/workers/workers/` is deliberate and not a typo. This is so we can support both Worker ID and aliased name: `/workers/workers/7f694d3716bc4a63ad285159ff1fa375` and `/workers/workers/my-worker` both work.
+- The deployments endpoint is unchanged because there's no change to the functionality at this time. It will be changed in the future to be consistent with the rest of the APIs.
+- We won't deprecate the ability to one-shot create a Worker and deployment without a better replacement.
+:::

src/content/docs/workers/platform/infrastructure-as-code.mdx

@@ -10,7 +10,7 @@ import { Icon } from "astro-icon/components";
 
 While [Wrangler](/workers/wrangler/configuration) makes it easy to upload and manage Workers, there are times when you need a more programmatic approach. This could involve using Infrastructure as Code (IaC) tools or interacting directly with the [Workers API](/api/resources/workers/). Examples include build and deploy scripts, CI/CD pipelines, custom developer tools, and automated testing.
 
-To make this easier, Cloudflare provides SDK libraries for popular languages, including [cloudflare-typescript](https://github.com/cloudflare/cloudflare-typescript) and [cloudflare-python](https://github.com/cloudflare/cloudflare-python). For IaC, you can use tools like HashiCorp's Terraform and the [Cloudflare Terraform Provider](/terraform) manage Workers resources.
+To make this easier, Cloudflare provides SDK libraries for popular languages such as [cloudflare-typescript](https://github.com/cloudflare/cloudflare-typescript) and [cloudflare-python](https://github.com/cloudflare/cloudflare-python). For IaC, you can use tools like HashiCorp's Terraform and the [Cloudflare Terraform Provider](/terraform) to manage Workers resources.
 
 Below are examples of deploying a Worker using different tools and languages, along with important considerations for managing Workers with IaC.
 
@@ -26,7 +26,7 @@ Generally, you'd run this bundling step before applying your Terraform plan or u
 wrangler deploy --dry-run --outdir build
 ```
 
-When using Wrangler for building but another method for uploading, make sure to copy all of your config from `wrangler.json` into your Terraform config, API request, or other. This is especially important with `compatibility_date` or flags your script relies on.
+When using Wrangler for building and a different method for uploading, make sure to copy all of your config from `wrangler.json` into your Terraform config or API request. This is especially important with `compatibility_date` or flags your script relies on.
 
 ## Terraform
 
@@ -40,6 +40,9 @@ variable "account_id" {
 resource "cloudflare_worker" "my_worker" {
   account_id = var.account_id
   name = "my-worker"
+  observability = {
+    enabled = true
+  }
 }
 
 resource "cloudflare_worker_version" "my_worker_version" {
@@ -68,14 +71,16 @@ resource "cloudflare_workers_deployment" "my_worker_deployment" {
 }
 ```
 
+Notice how you don't have to manage all of these resources in Terraform. For example, you could just the `cloudflare_worker` resource and seamlessly use Wrangler or your own deployment tools for Versions or Deployments.
+
 ## Cloudflare API Libraries
 
 This example uses the [cloudflare-typescript](https://github.com/cloudflare/cloudflare-typescript) SDK which provides convenient access to the Cloudflare REST API from server-side JavaScript or TypeScript.
 
 <GitHubCode
 	repo="cloudflare/cloudflare-typescript"
 	file="examples/workers/script-upload.ts"
-	commit="a7baf4fed47910228880800d5887a5d438baa6ad"
+	commit="cb55a45d615425f6aaf9ee8a237d2c5424bf30b7"
 	lang="ts"
 	useTypeScriptExample={true}
 />
@@ -346,3 +351,38 @@ EOF
 
 </TabItem>
 </Tabs>
+
+## Considerations with Durable Objects
+
+[Durable Object](/durable-objects/) migrations are applied with deployments. This means you can't bind to a durable object in a Version if a deployment doesn't exist i.e. migrations haven't been applied. For example, running this in Terraform will fail the first time the plan is applied:
+
+```tf
+resource "cloudflare_worker" "my_worker" {
+  account_id = var.account_id
+  name = "my-worker"
+}
+
+resource "cloudflare_worker_version" "my_worker_version" {
+  account_id = var.account_id
+  worker_id = cloudflare_worker.my_worker.id
+  bindings = [
+    {
+      type = "durable_object"
+      name = "my_durable_object"
+      class_name = "MyDurableObjectClass"
+    }
+  ]
+  migrations = {
+    new_sqlite_classes = [
+      "MyDurableObjectClass"
+    ]
+  }
+  # ...version props ommitted for brevity
+}
+
+resource "cloudflare_workers_deployment" "my_worker_deployment" {
+  # ...deployment props ommitted for brevity
+}
+```
+
+To make this succeed, you first have to comment out the `durable_object` binding block, apply the plan, uncomment it, comment out the `migrations` block, then apply again. This time the plan will succeed. This also applies to the API or SDKs. This is an example where it makes sense to just manage the `cloudflare_worker` and/or `cloudflare_workers_deployment` resources while using Wrangler for build and Version management.

src/content/docs/workers/static-assets/direct-upload.mdx

@@ -215,12 +215,12 @@ Optionally, an assets binding can be provided if you wish to fetch and serve ass
 
 ## Programmatic Example
 
-TODO update this with the prod commit
+This example is from [cloudflare-typescript](https://github.com/cloudflare/cloudflare-typescript/blob/main/examples/workers/script-with-assets-upload.ts).
 
 <GitHubCode
 	repo="cloudflare/cloudflare-typescript"
 	file="examples/workers/script-with-assets-upload.ts"
-	commit="a7baf4fed47910228880800d5887a5d438baa6ad"
+	commit="cb55a45d615425f6aaf9ee8a237d2c5424bf30b7"
 	lang="ts"
 	useTypeScriptExample={true}
 />