Deploy Workers Programatically

April 2, 2024 Engineering/Infrastructure

You can deploy Cloudflare Workers via the HTTP API and thus dynamically create Workers. The canonical solution for this is to use Workers for Platforms however you can also do it with a free Cloudflare account. Documentation for this feature is sparse but thanks to this Cloudflare Community post I came up with this:

Update: Well, turns out there is actually quite good documentation on that API in the Cloudflare API Docs 🙃.

1. Bundle your Worker

If you already have wrangler set up, you can bundle your worker by running wrangler build. This will build the worker into the dist/ folder.

2. Prepare your Metadata

Worker metadata is a configuration format that contains the runtime info from your wrangler.toml file. You can learn more about it in the Worker metadata docs.

Without any bindings, the minimum metadata might look like this:


3. Upload your Worker

Now upload your worker:

curl -X PUT "<ACCOUNT_ID>/workers/scripts/<SCRIPT_NAME>" \
    -H "Authorization: Bearer <CF_API_TOKEN>" \
    -H "Content-Type: multipart/form-data" \
    --form 'worker.js=@"dist/worker.js";type=application/javascript+module' \
    --form 'metadata="{\"main_module\":\"worker.js\",\"bindings\":[]}"'

  "result": {
    "created_on": "2024-04-02T21:27:40.527498Z",
    "modified_on": "2024-04-02T21:27:40.527498Z",
    "id": "<SCRIPT_NAME>",
    "tag": "aabbcc",
    "tags": [],
    "deployment_id": "aabbcc",
    "tail_consumers": null,
    "logpush": false,
    "etag": "aabbcc",
    "handlers": [
    "last_deployed_from": "api",
    "usage_model": "standard"
  "success": true,
  "errors": [],
  "messages": []

Notes on the params:

  • ACCOUNT_ID can be found in the Cloudflare dashboard URL
  • SCRIPT_NAME is the name of your new worker and will be part of the default subdomain
  • CF_API_TOKEN must be an Edit Cloudflare Workers API token

4. Publish the Worker via Subdomain

The last step is to publish the Worker to be accessible via subdomain. The domain for this will depend on the subdomain assigned for your Cloudflare account, e.g.: <SCRIPT_NAME>

curl -X POST "<ACCOUNT_ID>/workers/services/<SCRIPT_NAME>/environments/production/subdomain" \
 -H "Authorization: Bearer $CF_API_TOKEN" \
 -H "Content-Type: application/json" \
 -d '{"enabled": true}'
  "result": null,
  "success": true,
  "errors": [],
  "messages": []

Other Notes

June 13, 2024
Engineering/The 50-50 Goal
May 17, 2024
May 2, 2024
April 3, 2024
Engineering/Infrastructure/Deploy Workers Programatically
April 2, 2024
March 7, 2024
Engineering/Feature Flags
February 21, 2024
Engineering/Demo Culture
February 16, 2024
February 1, 2024
May 5, 2023
Engineering/ML/Jaccard Similarity
May 4, 2023
May 2, 2023
Engineering/Front-End/Modern Front-End Problems
November 3, 2022
Engineering/Test Matrixes
February 25, 2022
February 25, 2022
Engineering/Front-End/React’s Escape Hatch
February 21, 2022
January 1, 2022

About the author

Philipp Spiess
Philipp Spiess [ˈʃpiːs]

Engineer at Sourcegraph.
Prev: UI Engineer at Meta, curator of This Week in React, React DOM team member, and Team Lead at PSPDFKit.