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`

string

required

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

{
  "name": "my-worker"
}

`main`

string

Path to the entry point of your Worker.

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

`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`

string[]

Flags that enable or disable specific runtime features.

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

`account_id`

string

Your Cloudflare account ID.

{
  "account_id": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6"
}

Build Configuration

`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`

boolean

Whether to minify the Worker script.

{
  "minify": true
}

`define`

Record<string, string>

Replace global identifiers with constant expressions.

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

`tsconfig`

string

Path to a custom TypeScript config file.

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

Bindings

`vars`

Record<string, string>

Environment variables available in your Worker.

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

`kv_namespaces`

KVNamespace[]

KV namespace bindings.

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

Show KVNamespace properties

string

required

Variable name to access the namespace

string

required

KV namespace ID

string

KV namespace ID for local development

`durable_objects`

object

Durable Object bindings.

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

Show Binding properties

string

required

Variable name to access the namespace

string

required

Exported Durable Object class name

string

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

string

Environment of the script (production/staging)

`r2_buckets`

R2Bucket[]

R2 bucket bindings.

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

Show R2Bucket properties

string

required

Variable name to access the bucket

string

required

R2 bucket name

string

Bucket name for local development

string

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

`d1_databases`

D1Database[]

D1 database bindings.

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

Show D1Database properties

string

required

Variable name to access the database

string

required

Database name

string

required

Database UUID

`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

string

required

Variable name for the queue

string

required

Queue name

Show Consumer properties

string

required

Queue name to consume from

number

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

number

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

number

Number of retries on failure (default: 3)

string

Queue to send failed messages to

`services`

Service[]

Service bindings to other Workers.

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

Show Service properties

string

required

Variable name for the service

string

required

Name of the Worker to bind to

string

Named entrypoint to use

string

Environment of the service

`analytics_engine_datasets`

AnalyticsEngine[]

Analytics Engine dataset bindings.

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

Routing

`routes`

Route[]

Routes that trigger your Worker.

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

`route`

string

Single route pattern (alternative to routes).

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

Static Assets

`assets`

object

Configuration for Workers Assets.

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

Show Assets properties

string

required

Directory containing static files

string

Variable name for the assets binding

string[]

URL patterns to run Worker logic before serving assets

`site`

object

Configuration for Workers Sites (legacy).

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

Development

`dev`

object

Local development configuration.

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

Show Dev properties

number

Port to run dev server on

string

IP address to bind to

'http' | 'https'

Protocol for local server

'http' | 'https'

Protocol for upstream requests

Migrations

`migrations`

Migration[]

Durable Object migrations.

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

Show Migration properties

string

required

Unique identifier for this migration

string[]

Durable Object classes being added

object[]

Classes being renamed

string[]

Classes being removed

Observability

`logpush`

boolean

Enable Logpush for this Worker.

{
  "logpush": true
}

`tail_consumers`

TailConsumer[]

Workers to send tail logs to.

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

Limits

`limits`

object

Resource limits for your Worker.

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

Show Limit properties

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

​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

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