Configuration File Schema - Cloudflare Workers SDK

Wrangler uses a configuration file (typically wrangler.json or wrangler.toml) to define your Worker’s settings, bindings, and deployment options.

Configuration File Formats

Wrangler supports two configuration formats:

JSONC (.json or .jsonc): JSON with comments
TOML (.toml): Tom’s Obvious Minimal Language

For new projects, we recommend using JSONC format for better IDE support and validation.

Core Configuration

`name`

name

string

required

The name of your Worker. This is used in the Workers dashboard and CLI output.

{
  "name": "my-worker"
}

`main`

main

string

Path to the entry point of your Worker.

{
  "main": "src/index.ts"
}

`compatibility_date`

compatibility_date

string

required

A date in the form yyyy-mm-dd that specifies which version of the Workers runtime to use.

{
  "compatibility_date": "2024-01-01"
}

`compatibility_flags`

compatibility_flags

string[]

Flags that enable or disable specific runtime features.

{
  "compatibility_flags": [
    "nodejs_compat",
    "streams_enable_constructors"
  ]
}

`account_id`

account_id

string

Your Cloudflare account ID.

{
  "account_id": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6"
}

Build Configuration

`rules`

rules

Rule[]

Module import rules for non-JavaScript files.

{
  "rules": [
    {
      "type": "Text",
      "globs": ["**/*.txt"],
      "fallthrough": false
    },
    {
      "type": "Data",
      "globs": ["**/*.bin"]
    }
  ]
}

Show Rule types

ESModule - JavaScript/TypeScript modules
CommonJS - CommonJS modules
Text - Text files as strings
Data - Binary data as ArrayBuffer
CompiledWasm - WebAssembly modules

`minify`

minify

boolean

Whether to minify the Worker script.

{
  "minify": true
}

`define`

define

Record<string, string>

Replace global identifiers with constant expressions.

{
  "define": {
    "DEBUG": "false",
    "API_VERSION": "\"v1\""
  }
}

`tsconfig`

tsconfig

string

Path to a custom TypeScript config file.

{
  "tsconfig": "tsconfig.worker.json"
}

Bindings

`vars`

vars

Record<string, string>

Environment variables available in your Worker.

{
  "vars": {
    "API_KEY": "my-api-key",
    "ENVIRONMENT": "production"
  }
}

`kv_namespaces`

kv_namespaces

KVNamespace[]

KV namespace bindings.

{
  "kv_namespaces": [
    {
      "binding": "MY_KV",
      "id": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6"
    }
  ]
}

Show KVNamespace properties

binding

string

required

Variable name to access the namespace

string

required

KV namespace ID

preview_id

string

KV namespace ID for local development

`durable_objects`

durable_objects

object

Durable Object bindings.

{
  "durable_objects": {
    "bindings": [
      {
        "name": "MY_DO",
        "class_name": "MyDurableObject",
        "script_name": "do-worker"
      }
    ]
  }
}

Show Binding properties

name

string

required

Variable name to access the namespace

class_name

string

required

Exported Durable Object class name

script_name

string

Name of the Worker that defines this Durable Object (if different from current)

environment

string

Environment of the script (production/staging)

`r2_buckets`

r2_buckets

R2Bucket[]

R2 bucket bindings.

{
  "r2_buckets": [
    {
      "binding": "MY_BUCKET",
      "bucket_name": "my-bucket"
    }
  ]
}

Show R2Bucket properties

binding

string

required

Variable name to access the bucket

bucket_name

string

required

R2 bucket name

preview_bucket_name

string

Bucket name for local development

jurisdiction

string

Jurisdiction for the bucket (e.g., “eu”)

`d1_databases`

d1_databases

D1Database[]

D1 database bindings.

{
  "d1_databases": [
    {
      "binding": "DB",
      "database_name": "my-database",
      "database_id": "a1b2c3d4-e5f6-g7h8-i9j0-k1l2m3n4o5p6"
    }
  ]
}

Show D1Database properties

binding

string

required

Variable name to access the database

database_name

string

required

Database name

database_id

string

required

Database UUID

`queues`

queues

object

Queue bindings for producers and consumers.

{
  "queues": {
    "producers": [
      {
        "binding": "MY_QUEUE",
        "queue": "my-queue"
      }
    ],
    "consumers": [
      {
        "queue": "my-queue",
        "max_batch_size": 10,
        "max_batch_timeout": 5
      }
    ]
  }
}

Show Producer properties

binding

string

required

Variable name for the queue

queue

string

required

Queue name

Show Consumer properties

queue

string

required

Queue name to consume from

max_batch_size

number

Maximum messages per batch (default: 10, max: 100)

max_batch_timeout

number

Maximum seconds to wait before dispatching batch (default: 5)

max_retries

number

Number of retries on failure (default: 3)

dead_letter_queue

string

Queue to send failed messages to

`services`

services

Service[]

Service bindings to other Workers.

{
  "services": [
    {
      "binding": "AUTH_SERVICE",
      "service": "auth-worker",
      "entrypoint": "AuthAPI"
    }
  ]
}

Show Service properties

binding

string

required

Variable name for the service

service

string

required

Name of the Worker to bind to

entrypoint

string

Named entrypoint to use

environment

string

Environment of the service

`analytics_engine_datasets`

analytics_engine_datasets

AnalyticsEngine[]

Analytics Engine dataset bindings.

{
  "analytics_engine_datasets": [
    {
      "binding": "ANALYTICS"
    }
  ]
}

Routing

`routes`

routes

Route[]

Routes that trigger your Worker.

{
  "routes": [
    "example.com/*",
    { "pattern": "api.example.com/*", "zone_name": "example.com" }
  ]
}

`route`

route

string

Single route pattern (alternative to routes).

{
  "route": "example.com/*"
}

Static Assets

`assets`

assets

object

Configuration for Workers Assets.

{
  "assets": {
    "directory": "./public",
    "binding": "ASSETS",
    "run_worker_first": ["/api/*"]
  }
}

Show Assets properties

`site`

site

object

Configuration for Workers Sites (legacy).

{
  "site": {
    "bucket": "./public"
  }
}

Development

`dev`

dev

object

Local development configuration.

{
  "dev": {
    "port": 8787,
    "local_protocol": "http"
  }
}

Show Dev properties

port

number

Port to run dev server on

string

IP address to bind to

local_protocol

'http' | 'https'

Protocol for local server

upstream_protocol

'http' | 'https'

Protocol for upstream requests

Migrations

`migrations`

migrations

Migration[]

Durable Object migrations.

{
  "migrations": [
    {
      "tag": "v1",
      "new_classes": ["MyDurableObject"]
    },
    {
      "tag": "v2",
      "renamed_classes": [{
        "from": "MyDurableObject",
        "to": "MyDO"
      }]
    }
  ]
}

Show Migration properties

tag

string

required

Unique identifier for this migration

new_classes

string[]

Durable Object classes being added

renamed_classes

object[]

Classes being renamed

deleted_classes

string[]

Classes being removed

Observability

`logpush`

logpush

boolean

Enable Logpush for this Worker.

{
  "logpush": true
}

`tail_consumers`

tail_consumers

TailConsumer[]

Workers to send tail logs to.

{
  "tail_consumers": [
    {
      "service": "log-processor"
    }
  ]
}

Limits

`limits`

limits

object

Resource limits for your Worker.

{
  "limits": {
    "cpu_ms": 50
  }
}

Show Limit properties

cpu_ms

number

Maximum CPU time in milliseconds

Environment Overrides

You can define environment-specific overrides:

{
  "name": "my-worker",
  "vars": {
    "ENVIRONMENT": "production"
  },
  "env": {
    "staging": {
      "vars": {
        "ENVIRONMENT": "staging"
      },
      "kv_namespaces": [
        {
          "binding": "MY_KV",
          "id": "staging-kv-id"
        }
      ]
    }
  }
}

Deploy to staging:

wrangler deploy --env staging

Wrangler API

Miniflare API

Testing

Integrations

​Configuration File Formats

​Core Configuration

​name

​main

​compatibility_date

​compatibility_flags

​account_id

​Build Configuration

​rules

​minify

​define

​tsconfig

​Bindings

​vars

​kv_namespaces

​durable_objects

​r2_buckets

​d1_databases

​queues

​services

​analytics_engine_datasets

​Routing

​routes

​route

​Static Assets

​assets

​site

​Development

​dev

​Migrations

​migrations

​Observability

​logpush

​tail_consumers

​Limits

​limits

​Environment Overrides

Build docs developers (and LLMs) love

Configuration File Formats

Core Configuration

`name`

`main`

`compatibility_date`

`compatibility_flags`

`account_id`

Build Configuration

`rules`

`minify`

`define`

`tsconfig`

Bindings

`vars`

`kv_namespaces`

`durable_objects`

`r2_buckets`

`d1_databases`

`queues`

`services`

`analytics_engine_datasets`

Routing

`routes`

`route`

Static Assets

`assets`

`site`

Development

`dev`

Migrations

`migrations`

Observability

`logpush`

`tail_consumers`

Limits

`limits`

Environment Overrides