Configuration (18)·续

Configuration (18)·续

If you want to exclude files or directories in your bucket, add an exclude field to your [site] section of your Wrangler file:

{
    "site": {
        "bucket": "./public",
        "entry-point": "workers-site",
        "exclude": [ // must be an array.
            "excluded_dir"
        ]
    }
}

[site]
bucket = "./public"
entry-point = "workers-site"
exclude = [ "excluded_dir" ]

Wrangler will ignore files or directories matching the patterns in the exclude array when uploading assets to Workers KV.

Include > Exclude

If you provide both include and exclude fields, the include field will be used and the exclude field will be ignored.

Default ignored entries

Wrangler will always ignore:

node_modules
Hidden files and directories
Symlinks

More about include/exclude patterns

Refer to the gitignore documentation ↗︎ to learn more about the standard matching patterns.

Customizing your Sites Build

Workers Sites projects use webpack by default. Though you can bring your own webpack configuration, be aware of your entry and context settings.

You can also use the [build] section with Workers Sites, as long as your build step will resolve dependencies in node_modules. Refer to the custom builds section for more information.

triggers

A set of cron triggers used to call a Worker on a schedule.

Usage:

{
    "triggers": {
        "crons": [
            "0 0 * JAN-JUN FRI",
            "0 0 LW JUL-DEC *"
        ]
    }
}

[triggers]
crons = [ "0 0 * JAN-JUN FRI", "0 0 LW JUL-DEC *" ]

crons optional
A set of cron expressions ↗︎, where each expression is a separate schedule to run the Worker on.

dev

Arguments for wrangler dev can be configured here so you do not have to repeatedly pass them.

Usage:

{
    "dev": {
        "port": 9000,
        "local_protocol": "https"
    }
}

[dev]
port = 9_000
local_protocol = "https"

ip optional
IP address for the local wrangler dev server to listen on, defaults to 127.0.0.1.
port optional
Port for local wrangler dev server to listen on, defaults to 8787.
local_protocol optional
Protocol that local wrangler dev server listen to requests on, defaults to http.
upstream_protocol optional
Protocol that wrangler dev forwards requests on, defaults to https.

build

A custom build command for your project. There are two configurations based on the format of your Worker: service-worker and modules.

Service Workers

Service Workers are deprecated

Service Workers are deprecated, but still supported. We recommend using Module Workers instead. New features may not be supported for Service Workers.

This section is for customizing Workers with the service-worker format. These Workers use addEventListener and look like the following:

addEventListener("fetch", (event) => {
    event.respondWith(new Response("I'm a service Worker!"));
});

Usage:

{
    "build": {
        "command": "npm install && npm run build",
        "upload": {
            "format": "service-worker"
        }
    }
}

[build]
command = "npm install && npm run build"

[build.upload]
  format = "service-worker"

`[build]`

command optional
The command used to build your Worker. On Linux and macOS, the command is executed in the sh shell and the cmd shell for Windows. The && and || shell operators may be used.
cwd optional
The working directory for commands, defaults to the project root directory.
watch_dir optional
The directory to watch for changes while using wrangler dev, defaults to the src relative to the project root directory.

`[build.upload]`

format required
The format of the Worker script, must be "service-worker".

Note

Ensure the main field in your package.json references the Worker you want to publish.

Modules

Workers now supports the ES Modules syntax. This format allows you to export a collection of files and/or modules, unlike the Service Worker format which requires a single file to be uploaded.

Module Workers export their event handlers instead of using addEventListener calls.

Modules receive all bindings (KV Namespaces, Environment Variables, and Secrets) as arguments to the exported handlers. With the Service Worker format, these bindings are available as global variables.

Note

Refer to the fetch() handler documentation to learn more about the differences between the Service Worker and Module worker formats.

An uploaded module may import other uploaded ES Modules. If using the CommonJS format, you may require other uploaded CommonJS modules.

import html from "./index.html";

export default {
    // * request is the same as `event.request` from the service worker format
    // * waitUntil() and passThroughOnException() are accessible from `ctx` instead of `event` from the service worker format
    // * env is where bindings like KV namespaces, Durable Object namespaces, Config variables, and Secrets
    // are exposed, instead of them being placed in global scope.
    async fetch(request, env, ctx) {
        const headers = { "Content-Type": "text/html;charset=UTF-8" };
        return new Response(html, { headers });
    },
};

To create a Workers project using Wrangler and Modules, add a [build] section:

{
    "build": {
        "command": "npm install && npm run build",
        "upload": {
            "format": "modules",
            "main": "./worker.mjs"
        }
    }
}

[build]
command = "npm install && npm run build"

[build.upload]
  format = "modules"
  main = "./worker.mjs"

`[build]`

command optional
The command used to build your Worker. On Linux and macOS system, the command is executed in the sh shell and the cmd shell for Windows. The && and || shell operators may be used.
cwd optional
The working directory for commands, defaults to the project root directory.
watch_dir optional
The directory to watch for changes while using wrangler dev, defaults to the src relative to the project root directory.

`[build.upload]`

format required
The format of the Workers script, must be "modules".
dir optional
The directory you wish to upload your modules from, defaults to the dist relative to the project root directory.
main required
The relative path of the main module from dir, including the ./ prefix. The main module must be an ES module. For projects with a build script, this usually refers to the output of your JavaScript bundler.

Note

If your project is written using CommonJS modules, you will need to re-export your handlers and Durable Object classes using an ES module shim. Refer to the modules-webpack-commonjs ↗︎ template as an example.

rules optional
An ordered list of rules that define which modules to import, and what type to import them as. You will need to specify rules to use Text, Data, and CompiledWasm modules, or when you wish to have a .js file be treated as an ESModule instead of CommonJS.

Defaults:

{
    // You do not need to include these default rules in your [Wrangler configuration file](/workers/wrangler/configuration/), they are implicit.
    // The default rules are treated as the last two rules in the list.
    "build": {
        "upload": {
            "format": "modules",
            "main": "./worker.mjs",
            "rules": [
                {
                    "type": "ESModule",
                    "globs": [
                        "**/*.mjs"
                    ]
                },
                {
                    "type": "CommonJS",
                    "globs": [
                        "**/*.js",
                        "**/*.cjs"
                    ]
                }
            ]
        }
    }
}

[build.upload]
format = "modules"
main = "./worker.mjs"

[[build.upload.rules]]
  type = "ESModule"
  globs = [ "**/*.mjs" ]

[[build.upload.rules]]
  type = "CommonJS"
  globs = [ "**/*.js", "**/*.cjs" ]

type required
The module type, see the table below for acceptable options:
globs required
UNIX-style glob rules ↗︎ that are used to determine the module type to use for a given file in dir. Globs are matched against the module's relative path from build.upload.dir without the ./ prefix. Rules are evaluated in order, starting at the top.
fallthrough optional
This option allows further rules for this module type to be considered if set to true. If not specified or set to false, further rules for this module type will be ignored.

Example

To illustrate how these levels are applied, here is a Wrangler file using multiple environments:

{
    "$schema": "./node_modules/wrangler/config-schema.json",
    // top level configuration
    "type": "javascript",
    "name": "my-worker-dev",
    "account_id": "12345678901234567890",
    "zone_id": "09876543210987654321",
    "route": "dev.example.com/*",
    "usage_model": "unbound",
    "kv_namespaces": [
        {
            "binding": "FOO",
            "id": "b941aabb520e61dcaaeaa64b4d8f8358",
            "preview_id": "03c8c8dd3b032b0528f6547d0e1a83f3"
        },
        {
            "binding": "BAR",
            "id": "90e6f6abd5b4f981c748c532844461ae",
            "preview_id": "e5011a026c5032c09af62c55ecc3f438"
        }
    ],
    "build": {
        "command": "webpack",
        "upload": {
            "format": "service-worker"
        }
    },
    "site": {
        "bucket": "./public",
        "entry-point": "workers-site"
    },
    "dev": {
        "ip": "0.0.0.0",
        "port": 9000,
        "local_protocol": "http",
        "upstream_protocol": "https"
    },
    "env": {
        // environment configuration
        "staging": {
            "name": "my-worker-staging",
            "route": "staging.example.com/*",
            "kv_namespaces": [
                {
                    "binding": "FOO",
                    "id": "0f2ac74b498b48028cb68387c421e279"
                },
                {
                    "binding": "BAR",
                    "id": "068c101e168d03c65bddf4ba75150fb0"
                }
            ]
        },
        // environment configuration
        "production": {
            "workers_dev": true,
            "kv_namespaces": [
                {
                    "binding": "FOO",
                    "id": "0d2ac74b498b48028cb68387c421e233"
                },
                {
                    "binding": "BAR",
                    "id": "0d8c101e168d03c65bddf4ba75150f33"
                }
            ]
        }
    }
}

"$schema" = "./node_modules/wrangler/config-schema.json"
type = "javascript"
name = "my-worker-dev"
account_id = "12345678901234567890"
zone_id = "09876543210987654321"
route = "dev.example.com/*"
usage_model = "unbound"

[[kv_namespaces]]
binding = "FOO"
id = "b941aabb520e61dcaaeaa64b4d8f8358"
preview_id = "03c8c8dd3b032b0528f6547d0e1a83f3"

[[kv_namespaces]]
binding = "BAR"
id = "90e6f6abd5b4f981c748c532844461ae"
preview_id = "e5011a026c5032c09af62c55ecc3f438"

[build]
command = "webpack"

[build.upload]
  format = "service-worker"

[site]
bucket = "./public"
entry-point = "workers-site"

[dev]
ip = "0.0.0.0"
port = 9_000
local_protocol = "http"
upstream_protocol = "https"

[env.staging]
name = "my-worker-staging"
route = "staging.example.com/*"

[[env.staging.kv_namespaces]]
  binding = "FOO"
  id = "0f2ac74b498b48028cb68387c421e279"

[[env.staging.kv_namespaces]]
  binding = "BAR"
  id = "068c101e168d03c65bddf4ba75150fb0"

[env.production]
workers_dev = true

[[env.production.kv_namespaces]]
  binding = "FOO"
  id = "0d2ac74b498b48028cb68387c421e233"

[[env.production.kv_namespaces]]
  binding = "BAR"
  id = "0d8c101e168d03c65bddf4ba75150f33"

Was this helpful?

YesNo

{"@context":"https://schema.org","@type":"TechArticle","@id":"https://developers.cloudflare.com/workers/wrangler/configuration/#page","headline":"Configuration","description":"Learn how to configure your Cloudflare Worker using Wrangler v1. This guide covers top-level and environment-specific settings, key types, and deployment options.","url":"https://developers.cloudflare.com/workers/wrangler/configuration/","inLanguage":"en","image":"https://developers.cloudflare.com/workers/wrangler/migration/v1-to-v2/wrangler-legacy/configuration/og.png?v=757cd9bbad5852dd","dateModified":"2026-04-23","publisher":{"@type":"Organization","name":"Cloudflare","description":"One platform for your apps, agents, and workforce. Build, secure, and scale without managing infrastructure","url":"https://www.cloudflare.com/","sameAs":["https://github.com/cloudflare","https://www.linkedin.com/company/cloudflare","https://x.com/cloudflare"],"logo":{"@type":"ImageObject","url":"https://developers.cloudflare.com/logo.svg"},"address":{"@type":"PostalAddress","streetAddress":"101 Townsend St","addressLocality":"San Francisco","addressRegion":"CA","postalCode":"94107","addressCountry":"US"},"contactPoint":[{"@type":"ContactPoint","contactType":"Customer Support","url":"https://support.cloudflare.com/","availableLanguage":["English"]},{"@type":"ContactPoint","contactType":"Sales","url":"https://www.cloudflare.com/contact/","availableLanguage":["English"]}]},"isPartOf":{"@type":"WebSite","@id":"https://developers.cloudflare.com/#website","name":"Cloudflare Docs","url":"https://developers.cloudflare.com/"}}

description: Install or update Wrangler v1 using npm or Cargo. Now deprecated in favor of the latest Wrangler release. title: Install / Update image: https://developers.cloudflare.com/workers/wrangler/migration/v1-to-v2/wrangler-legacy/install-update/og.png?v=1e1d3ae0f48926f6

Documentation Index
Fetch the complete documentation index at: https://developers.cloudflare.com/workers/llms.txt
Use this file to discover all available pages before exploring further.

Configuration (18)·续

Configuration (18)·续

Include > Exclude

Default ignored entries

More about include/exclude patterns

Customizing your Sites Build

triggers

dev

build

Service Workers

[build]

[build.upload]

Modules

[build]

[build.upload]

Example

On this page

`[build]`

`[build.upload]`

`[build]`

`[build.upload]`