Worker A Cloudflare Worker is a serverless function that runs on Cloudflare’s global network.
Props The entrypoint for the worker script. const worker = await Worker ( "api" , { entrypoint: "./src/worker.ts" });
Inline worker script (alternative to entrypoint). const worker = await Worker ( "api" , { script: "export default { fetch() { return new Response('Hello'); } }" });
Name for the worker. ${app}-${stage}-${id}
Bindings to attach to the worker. const worker = await Worker ( "api" , { entrypoint: "./src/worker.ts" , bindings: { BUCKET: bucket , KV: kvNamespace , DB: database } });
Whether to enable a workers.dev URL for this worker. If true, the worker will be available at {name}.{subdomain}.workers.dev
Routes to create for this worker. const worker = await Worker ( "api" , { entrypoint: "./src/worker.ts" , routes: [ "api.example.com/*" , { pattern: "sub.example.com/*" , zoneId: "1234567890" } ] });
domains
(string | DomainConfig)[]
Custom domains to bind to the worker. const worker = await Worker ( "api" , { entrypoint: "./src/worker.ts" , domains: [ "api.example.com" , { domainName: "example.com" , zoneId: "1234567890" } ] });
The compatibility date for the worker. Automatically pinned to the latest Workers release
The compatibility flags for the worker.
Compatibility preset to automatically include common compatibility flags.
"node": Includes nodejs_compat flag for Node.js compatibility Cron expressions for the trigger. Uses standard cron syntax. const worker = await Worker ( "scheduled" , { entrypoint: "./src/scheduled.ts" , crons: [ '0 0 * * *' , '0 12 * * MON' ] });
Event sources that this worker will consume. const worker = await Worker ( "processor" , { entrypoint: "./src/processor.ts" , bindings: { QUEUE: queue }, eventSources: [{ queue , settings: { batchSize: 15 , maxConcurrency: 3 , maxRetries: 5 } }] });
Configuration for static assets. Contents of a _headers file (used to attach custom headers on asset responses).
Contents of a _redirects file (used to apply redirects or proxy paths).
html_handling
string
default: "auto-trailing-slash"
Determines the redirects and rewrites of requests for HTML content. Options: "auto-trailing-slash" | "force-trailing-slash" | "drop-trailing-slash" | "none"
Determines the response when a request does not match a static asset. Options: "none" | "404-page" | "single-page-application"
run_worker_first
boolean | string[]
default: "false"
When true, requests will always invoke the Worker script.
If an array is passed, the worker will be invoked for matching requests.
Placement configuration for the worker. Enable smart placement mode. Cloudflare automatically places your Worker closest to the upstream with the most requests. const worker = await Worker ( "api" , { entrypoint: "./src/worker.ts" , placement: { mode: "smart" } });
Cloud provider region to place your Worker closest to. Format: {provider}:{region} const worker = await Worker ( "api" , { entrypoint: "./src/worker.ts" , placement: { region: "aws:us-east-1" } });
Host endpoint to probe (TCP/layer 4) for placement. Format: hostname:port const worker = await Worker ( "api" , { entrypoint: "./src/worker.ts" , placement: { host: "my-database.example.com:5432" } });
Hostname to probe (HTTP/layer 7) for placement. const worker = await Worker ( "api" , { entrypoint: "./src/worker.ts" , placement: { hostname: "my-api.example.com" } });
Resource limits for the worker. The maximum CPU time in milliseconds that the worker can use.
The maximum number of subrequests allowed per invocation.
Defaults to 50 for free accounts and 10,000 for paid accounts.
Specify the observability behavior of the Worker. If observability is enabled for this Worker.
A number between 0 and 1, where 0 indicates zero requests are logged, and 1 indicates every request is logged.
Enable Workers Logpush to export trace events to external destinations. Requires a separate Logpush job configuration via the Cloudflare API.
Version label for this worker deployment. When specified, the worker will be published as a version with this label instead of updating the live deployment. const worker = await Worker ( "my-worker" , { entrypoint: "./src/worker.ts" , version: "pr-123" });
Output The worker’s URL if enabled. Format: {name}.{subdomain}.workers.dev
The bindings that were created.
The routes that were created for this worker.
The custom domains that were created for this worker.
The compatibility date for the worker.
The compatibility flags for the worker.
Examples Basic HTTP Handler const api = await Worker ( "api" , { name: "api-worker" , entrypoint: "./src/api.ts" , url: true });
Worker with Bindings const bucket = await R2Bucket ( "storage" ); const kv = await KVNamespace ( "cache" ); const db = await D1Database ( "db" ); const worker = await Worker ( "api" , { entrypoint: "./src/worker.ts" , bindings: { BUCKET: bucket , CACHE: kv , DB: db } });
Worker with Custom Domain const worker = await Worker ( "api" , { entrypoint: "./src/api.ts" , domains: [ "api.example.com" ] });
Scheduled Worker const worker = await Worker ( "scheduled-tasks" , { entrypoint: "./src/scheduled.ts" , crons: [ '* 15 * * *' , '0 0 * * *' , '0 12 * * MON' ] });
Queue Consumer const queue = await Queue ( "tasks" ); const worker = await Worker ( "processor" , { entrypoint: "./src/processor.ts" , bindings: { QUEUE: queue }, eventSources: [{ queue , settings: { batchSize: 15 , maxConcurrency: 3 , maxRetries: 5 , maxWaitTimeMs: 2500 , retryDelay: 60 } }] });