Deploy Worker with wrangler deploy
Update the wrangler.toml file with the 'name' key set to your project name, then run 'npx wrangler deploy' to deploy the Worker. A .workers.dev domain will be automatically generated after deployment.
Cloudflare Workers · all subjects
deployment & versioning
20 notes, read out of this brain and free to use. Each one was extracted from a source and is re-checked against its exam.
Infrastructure as Code tools for Workers
Cloudflare Workers can be deployed and managed programmatically using Infrastructure as Code tools like HashiCorp's Terraform and the Cloudflare Terraform Provider, or directly via the Workers API. SDK libraries are available for popular languages including cloudflare-typescript and cloudflare-python.
Workers Bundling requirement for IaC deployment
When deploying Workers using IaC tools or the Workers API (not Wrangler), you must handle Workers Bundling separately before applying your deployment. Run `wrangler deploy --dry-run --outdir build` to generate the bundled output. All configuration from `wrangler.json` must be manually copied to your Terraform config or API request, including `compatibility_date` and any compatibility flags.
API token requirement for IaC
Infrastructure as Code deployments require an API token (not Global API key) and an account ID to function. Both are prerequisites for Terraform and API-based deployments.
Terraform cloudflare_workers_deployment resource
The `cloudflare_workers_deployment` Terraform resource creates a deployment for a Worker. Required fields: `account_id`, `script_name`, `strategy` ('percentage' or other strategy), and `versions` (array of version objects with `percentage` and `version_id`).
Cloudflare API SDK example with TypeScript
The cloudflare-typescript SDK provides programmatic access to the Cloudflare REST API. It requires CLOUDFLARE_API_TOKEN, CLOUDFLARE_ACCOUNT_ID environment variables, and optionally CLOUDFLARE_SUBDOMAIN. Create a Worker using `client.workers.beta.workers.create()`, create a version using `client.workers.beta.workers.versions.create()`, and create a deployment using `client.workers.scripts.deployments.create()`. The SDK throws `Cloudflare.NotFoundError` for 404 responses.
REST API beta for Worker management
The beta REST API for creating and managing Workers uses JSON endpoints at paths like `/client/v4/accounts/{account_id}/workers/workers` for creating Workers, `/client/v4/accounts/{account_id}/workers/workers/{worker_id}/versions` for creating versions, and `/client/v4/accounts/{account_id}/workers/scripts/{worker_name}/deployments` for creating deployments.
REST API base64 encoding for Worker scripts
When uploading Worker scripts via the REST API, encode the script content as base64 and include it in the `content_base64` field within the modules array. Set `compatibility_date` to a date like '2025-08-06', `main_module` to the module filename, and `content_type` to 'application/javascript+module' for JavaScript.
multipart/form-data API for Worker upload
The stable multipart/form-data API endpoint for uploading Workers is at `/client/v4/accounts/{account_id}/workers/scripts/{worker_name}` using PUT. It automatically creates a version and deployment. Provide metadata as JSON (with `main_module`, `bindings`, `compatibility_date`) and the script file separately in the form data.
Python Workers REST API upload
To upload Python Workers via the REST API, use `content_type: "text/x-python"` for the module and include the `python_workers` compatibility flag in the `compatibility_flags` array. The multipart/form-data API also supports Python with the same content type and flag.
Workers for Platforms dispatch namespace API
To upload a User Worker to a dispatch namespace in Workers for Platforms, use the endpoint `/client/v4/accounts/{account_id}/workers/dispatch/namespaces/{dispatch_namespace}/scripts/{script_name}` with PUT. First create the dispatch namespace at `/client/v4/accounts/{account_id}/workers/dispatch/namespaces` with POST.
Worker versions are immutable and append-only
Worker versions are immutable at the API level and cannot be updated after creation. Meaningful changes to a `cloudflare_worker_version` Terraform resource trigger replacement, creating a new version but not deleting the previous one. This ensures a complete version history. When the parent `cloudflare_worker` resource is deleted, all associated versions are also deleted.
Worker version module content options
Worker version modules support two mutually exclusive ways to provide content: `content_file` (points to a local file, preferred to avoid bloating state) or `content_base64` (inline base64-encoded content). Changes are tracked using the computed `content_sha256` attribute.
Terraform import of cloudflare_worker_version uses content_base64
When importing a `cloudflare_worker_version` Terraform resource using `terraform import cloudflare_worker_version.my_worker_version <account_id>/<worker_id>/<version_id>`, Terraform always populates the `content_base64` attribute in state regardless of the attribute used in config. If config uses `content_file`, there will be a mismatch after import. This is expected and will result in an in-place update if the `content_sha256` values match.
Cloudflare TypeScript SDK Worker creation example
Example of creating and deploying a Worker using cloudflare-typescript SDK: call `client.workers.beta.workers.create()` with `account_id` and `name`, then `client.workers.beta.workers.versions.create()` with the worker ID and version details (compatibility_date, main_module, modules array with content_base64, bindings), then `client.workers.scripts.deployments.create()` with strategy 'percentage' and versions array.
REST API curl example for Worker creation
Example: Create a Worker with POST to `/client/v4/accounts/$account_id/workers/workers` with JSON body `{"name": "worker-name"}`. Create a version with POST to `/client/v4/accounts/$account_id/workers/workers/$worker_id/versions` with compatibility_date, main_module, modules array (with name, content_type, content_base64), and bindings. Create deployment with POST to `/client/v4/accounts/$account_id/workers/scripts/$worker_name/deployments` with strategy and versions array.
Terraform content_file example
Terraform `cloudflare_worker_version` resource using `content_file`: specify `modules` array with name 'worker.js', content_type 'application/javascript+module', and `content_file = "build/worker.js"` pointing to the local bundled file.
Terraform content_base64 example
Terraform `cloudflare_worker_version` resource using `content_base64`: specify `modules` array with name 'worker.js', content_type 'application/javascript+module', and `content_base64 = base64encode("export default { async fetch() { return new Response('Hello world!') } }")` with inline base64-encoded script.
Mix IaC resources with Wrangler
You do not need to manage all Terraform resources together. For example, you could use only the `cloudflare_worker` resource and seamlessly use Wrangler for managing versions and deployments. This is useful when Durable Object migrations are involved, where Terraform apply initially fails due to binding requirements.
Migrate from wrangler pages deploy to wrangler deploy
When migrating from Cloudflare Pages to Workers, replace Pages deployment commands with Workers commands. Use `wrangler deploy` instead of `wrangler pages deploy`, and use `wrangler dev` instead of `wrangler pages dev`.