Worker

The Worker component lets you create a Cloudflare Worker.

Minimal example

new sst.cloudflare.Worker("MyWorker", {
  handler: "src/worker.handler"
});

Link resources

Link resources to the Worker. This will handle the credentials and allow you to access it in your handler.

const bucket = new sst.aws.Bucket("MyBucket");

new sst.cloudflare.Worker("MyWorker", {
  handler: "src/worker.handler",
  link: [bucket]
});

You can use the SDK to access the linked resources in your handler.

import { Resource } from "sst";

console.log(Resource.MyBucket.name);

Enable URLs

Enable worker URLs to invoke the worker over HTTP.

new sst.cloudflare.Worker("MyWorker", {
  handler: "src/worker.handler",
  url: true
});

Bundling

Customize how SST uses esbuild to bundle your worker code with the build property.

new sst.cloudflare.Worker("MyWorker", {
  handler: "src/worker.handler",
  build: {
    install: ["pg"]
  }
});

Constructor

new Worker(name, args, opts?)

Parameters

name string
args WorkerArgs
opts? ComponentResourceOptions

WorkerArgs

build?

Type Input<Object>

banner?
esbuild?
loader?
minify?

Configure how your function is bundled.

SST bundles your worker code using esbuild. This tree shakes your code to only include what’s used.

Type Input<string>

Use this to insert a string at the beginning of the generated JS file.

{
  build: {
    banner: "console.log('Function starting')"
  }
}

build.esbuild?

Type Input<EsbuildOptions>

This allows you to customize esbuild config that is used.

build.loader?

Type Input<Record<string, Loader>>

Configure additional esbuild loaders for other file extensions. This is useful when your code is importing non-JS files like .png, .css, etc.

{
  build: {
    loader: {
     ".png": "file"
    }
  }
}

build.minify?

Type Input<boolean>

Default true

Disable if the worker code should be minified when bundled.

{
  build: {
    minify: false
  }
}

compatibility?

Type Input<Object>

date?
flags?

Configure Cloudflare compatibility for the Worker.

compatibility.date?

Type Input<string>

Default “2025-05-05”

The Cloudflare compatibility date for the Worker.

SST uses this for both the uploaded Worker and for deciding which native Node.js modules should stay external during bundling.

compatibility.flags?

Type Input<Input<string>[]>

Default [“nodejs_compat”]

The Cloudflare compatibility flags for the Worker.

SST uses this for both the uploaded Worker and for deciding which native Node.js modules should stay external during bundling.

domain?

Type Input<string> | Object

aliases?
name
redirects?

Set a custom domain for your Worker. Supports domains hosted on Cloudflare.

{
  domain: "domain.com"
}

You can also redirect alternate domains to the main domain.

{
  domain: {
    name: "domain.com",
    redirects: ["www.domain.com"]
  }
}

Or keep visitors on alternate domains with aliases.

{
  domain: {
    name: "app1.domain.com",
    aliases: ["app2.domain.com"]
  }
}

domain.aliases?

Type Input<string>[]

Alias domains that should be used. Unlike the redirects option, this keeps your visitors on this alias domain.

So if your users visit app2.domain.com, they will stay on app2.domain.com in their browser.

{
  domain: {
    name: "app1.domain.com",
    aliases: ["app2.domain.com"]
  }
}

domain.name

Type Input<string>

The custom domain you want to use.

{
  domain: {
    name: "example.com"
  }
}

domain.redirects?

Type Input<string>[]

Alternate domains to be used. Visitors to the alternate domains will be redirected to the main name.

Use this to create a www. version of your domain and redirect visitors to the apex domain.

{
  domain: {
    name: "domain.com",
    redirects: ["www.domain.com"]
  }
}

environment?

Type Input<Record<string, Input<string>>>

Key-value pairs that are set as Worker environment variables.

They can be accessed in your worker through env.<key>.

{
  environment: {
    DEBUG: "true"
  }
}

handler

Type Input<string>

Path to the handler file for the worker.

The handler path is relative to the root your repo or the sst.config.ts.

{
  handler: "packages/functions/src/worker.ts"
}

link?

Type Input<any[]>

Link resources to your worker. This will:

Handle the credentials needed to access the resources.
Allow you to access it in your site using the SDK.

Takes a list of components to link to the function.

{
  link: [bucket, stripeKey]
}

migrations?

Type Input<Input<WorkerDurableObjectMigration>[]>

Durable Object migrations for this worker.

This follows Wrangler’s top-level migrations config. Keep the full, ordered migration history here; SST reads the Worker’s current migration tag and uploads the pending migrations as Cloudflare’s oldTag, newTag, and steps payload. If there is no current tag, SST uploads the full history as the initial migration payload. If the current tag is not in the configured history, SST follows Wrangler and uploads all configured migrations with the current tag as oldTag.

Each migration needs a unique tag. Add a migration when you create, rename, delete, or transfer a Durable Object class. Updating code for an existing class does not require one.

On the first deploy, add each new class with newSqliteClasses. For a rename, keep the original migration and append a new migration with renamedClasses. Do not declare the renamed class as a new class, or Cloudflare will reject the deploy or create a separate namespace.

{
  migrations: [{
    tag: "v1",
    newSqliteClasses: ["Counter"]
  }]
}

{
  migrations: [
    {
      tag: "v1",
      newSqliteClasses: ["Counter"],
    },
    {
      tag: "v2",
      renamedClasses: [{ from: "Counter", to: "CounterV2" }],
    },
  ]
}

placement?

Type Input<Object>

host?
hostname?
mode?
region?

Configure placement for your Worker.

Smart Placement

{
  placement: {
    mode: "smart"
  }
}

Explicit region

{
  placement: {
    region: "aws:us-east-1"
  }
}

placement.host?

Type Input<string>

placement.hostname?

Type Input<string>

placement.mode?

Type Input<string>

placement.region?

Type Input<string>

transform?

Type Object

worker?

Transform how this component creates its underlying resources.

transform.worker?

Type WorkersScriptArgs | (args: WorkersScriptArgs, opts: ComponentResourceOptions, name: string) => void

Transform the Worker resource.

url?

Type Input<boolean>

Default false

Enable a dedicated endpoint for your Worker.

Properties

nodes

Type Object

worker

The underlying resources this component creates.

nodes.worker

Type WorkersScript

The Cloudflare Worker script.

url

Type Output<undefined | string>

The Worker URL if url is enabled.

SDK

Use the SDK in your runtime to interact with your infrastructure.

Bindings

When you link a worker, say WorkerA, to another worker, WorkerB; it automatically creates a service binding between the workers. It allows WorkerA to call WorkerB without going through a publicly-accessible URL.

import { Resource } from "sst";

await Resource.WorkerB.fetch(request);

WorkerDomainArgs

aliases?

Type Input<string>[]

Alias domains that should be used. Unlike the redirects option, this keeps your visitors on this alias domain.

So if your users visit app2.domain.com, they will stay on app2.domain.com in their browser.

{
  domain: {
    name: "app1.domain.com",
    aliases: ["app2.domain.com"]
  }
}

name

Type Input<string>

The custom domain you want to use.

{
  domain: {
    name: "example.com"
  }
}

redirects?

Type Input<string>[]

Alternate domains to be used. Visitors to the alternate domains will be redirected to the main name.

Use this to create a www. version of your domain and redirect visitors to the apex domain.

{
  domain: {
    name: "domain.com",
    redirects: ["www.domain.com"]
  }
}

from
to

Durable Object classes to rename.

from
fromScript
to

Durable Object classes to transfer from another script.