Worker

API reference for Cloudflare Worker resource

Worker

A Cloudflare Worker is a serverless function that runs on Cloudflare’s global network.

Props

entrypoint · string

The entrypoint for the worker script.

const worker = await Worker("api", {
  entrypoint: "./src/worker.ts"
});

script · string

Inline worker script (alternative to entrypoint).

const worker = await Worker("api", {
  script: "export default { fetch() { return new Response('Hello'); } }"
});

name · string

Name for the worker.

Hide default

${app}-${stage}-${id}

bindings · Bindings

Bindings to attach to the worker.

const worker = await Worker("api", {
  entrypoint: "./src/worker.ts",
  bindings: {
    BUCKET: bucket,
    KV: kvNamespace,
    DB: database
  }
});

url · boolean · default: "false"

Whether to enable a workers.dev URL for this worker.

If true, the worker will be available at {name}.{subdomain}.workers.dev

routes · (string | RouteConfig)[]

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" }
  ]
});

compatibilityDate · string

The compatibility date for the worker.

Hide default

Automatically pinned to the latest Workers release

compatibilityFlags · string[]

The compatibility flags for the worker.

compatibility · CompatibilityPreset

Compatibility preset to automatically include common compatibility flags.

• "node": Includes nodejs_compat flag for Node.js compatibility

crons · string[]

Cron expressions for the trigger. Uses standard cron syntax.

const worker = await Worker("scheduled", {
  entrypoint: "./src/scheduled.ts",
  crons: ['0 0 * * *', '0 12 * * MON']
});

eventSources · EventSource[]

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
    }
  }]
});

assets · AssetsConfig

Configuration for static assets.

Show properties

_headers · string

Contents of a _headers file (used to attach custom headers on asset responses).

_redirects · string

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"

not_found_handling · string · default: "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 · WorkerPlacement

Placement configuration for the worker.

Show properties

mode · smart

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" }
});

region · string

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 · string

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 · string

Hostname to probe (HTTP/layer 7) for placement.

const worker = await Worker("api", {
  entrypoint: "./src/worker.ts",
  placement: { hostname: "my-api.example.com" }
});

limits · object

Resource limits for the worker.

Show properties

cpu_ms · number · default: "30000"

The maximum CPU time in milliseconds that the worker can use.

subrequests · number

The maximum number of subrequests allowed per invocation. Defaults to 50 for free accounts and 10,000 for paid accounts.

observability · WorkerObservability

Specify the observability behavior of the Worker.

Show properties

enabled · boolean · default: "true"

If observability is enabled for this Worker.

headSamplingRate · number · default: "1"

A number between 0 and 1, where 0 indicates zero requests are logged, and 1 indicates every request is logged.

logpush · boolean · default: "false"

Enable Workers Logpush to export trace events to external destinations.

Requires a separate Logpush job configuration via the Cloudflare API.

version · string

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

id · string

The ID of the worker.

name · string

The name of the worker.

url · string

The worker’s URL if enabled. Format: {name}.{subdomain}.workers.dev

bindings · Bindings

The bindings that were created.

routes · Route[]

The routes that were created for this worker.

domains · CustomDomain[]

The custom domains that were created for this worker.

compatibilityDate · string

The compatibility date for the worker.

compatibilityFlags · string[]

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
    }
  }]
});