Worker

The Worker component lets you create a Cloudflare Worker.

Minimal example

sst.config.ts

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.

sst.config.ts

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.

src/worker.ts

import { Resource } from "sst";

console.log(Resource.MyBucket.name);

Enable URLs

Enable worker URLs to invoke the worker over HTTP.

sst.config.ts

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.

sst.config.ts

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.

build.banner?

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.

Tip

Check out the JS tab in the code snippets in the esbuild docs for the BuildOptions.

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.

Tip

You can migrate an externally hosted domain to Cloudflare by following this guide.

{
  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.

Note

Unlike the aliases option, this will redirect visitors back 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:

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

Takes a list of components to link to the function.

{
  link: [bucket, stripeKey]
}

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.

---

Links

This is accessible through the Resource object in the SDK.

• url undefined | string

  The Worker URL if url is enabled.

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.

index.ts

import { Resource } from "sst";

await Resource.WorkerB.fetch(request);

Read more about binding Workers.

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.

Note

Unlike the aliases option, this will redirect visitors back 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"]
  }
}