Configuration (17)·续5

Configuration (17)·续5

port number optional
Port for the local dev server to listen on. Defaults to 8787.
inspector_port number optional
Port for the local dev server's inspector (DevTools) to listen on. Defaults to 9229. If you do not set this and the default port is in use, Wrangler picks another available port. Set this when you run several dev servers at once and need each inspector on a predictable port. The --inspector-port flag overrides this value.
inspector_ip string optional
IP address for the local dev server's inspector to listen on. Defaults to 127.0.0.1.
local_protocol string optional
Protocol that local dev server listens to requests on. Defaults to http.
upstream_protocol string optional
Protocol that the local dev server forwards requests on. Defaults to https.
host string optional
Host to forward requests to, defaults to the host of the first route of the Worker.
enable_containers boolean optional
Determines whether to enable containers during a local dev session, if they have been configured. Defaults to true. If set to false, you can develop the rest of your application without requiring Docker or other container tool, as long as you do not invoke any code that interacts with containers.
container_engine string optional
Used for local development of Containers. Wrangler will attempt to automatically find the correct socket to use to communicate with your container engine. If that does not work (usually surfacing as an internal error when attempting to connect to your Container), you can try setting the socket path using this option. You can also set this via the environment variable DOCKER_HOST.
generate_types boolean optional
Generate types from your Worker configuration. Defaults to false.

{
    "dev": {
        "ip": "192.168.1.1",
        "port": 8080,
        "inspector_port": 9230,
        "local_protocol": "http",
    },
}

[dev]
ip = "192.168.1.1"
port = 8_080
inspector_port = 9_230
local_protocol = "http"

Secrets

Secrets are a type of binding that allow you to attach encrypted text values to your Worker.

`secrets` configuration property

The secrets configuration property lets you declare the secret names your Worker requires in your Wrangler configuration file. Required secrets are validated during local development and deploy, and used as the source of truth for type generation.

{
    "secrets": {
        "required": ["API_KEY", "DB_PASSWORD"],
    },
}

[secrets]
required = [ "API_KEY", "DB_PASSWORD" ]

Type generation

When secrets is defined at any config level, wrangler types generates typed bindings from the names listed in secrets.required and no longer infers secret names from .dev.vars or .env files. This lets you run type generation in environments where those files are not present.

Per-environment secrets are supported. Each named environment produces its own interface, and the aggregated Env type marks secrets that only appear in some environments as optional.

Deploy

When secrets is defined, wrangler deploy and wrangler versions upload validate that all secrets in secrets.required are configured on the Worker before the operation succeeds. If any required secrets are missing, the command fails with an error listing which secrets need to be set.

Local development

Caution

Do not use vars to store sensitive information in your Worker's Wrangler configuration file. Use secrets instead.

Put secrets for use in local development in either a .dev.vars file or a .env file, in the same directory as the Wrangler configuration file.

Note

You can use the secrets configuration property to declare which secret names your Worker requires. When defined, only the keys listed in secrets.required are loaded from .dev.vars or .env. Additional keys are excluded and missing keys produce a warning.

Note

Choose to use either .dev.vars or .env but not both. If you define a .dev.vars file, then values in .env files will not be included in the env object during local development.

These files should be formatted using the dotenv ↗︎ syntax. For example:

.dev.vars / .envbash

SECRET_KEY="value"
API_TOKEN="eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9"

Do not commit secrets to git

The .dev.vars and .env files should not be committed to git. Add .dev.vars* and .env* to your project's .gitignore file.

To set different secrets for each Cloudflare environment, create files named .dev.vars.<environment-name> or .env.<environment-name>.

When you select a Cloudflare environment in your local development, the corresponding environment-specific file will be loaded ahead of the generic .dev.vars (or .env) file.

When using .dev.vars.<environment-name> files, all secrets must be defined per environment. If .dev.vars.<environment-name> exists then only this will be loaded; the .dev.vars file will not be loaded.
In contrast, all matching .env files are loaded and the values are merged. For each variable, the value from the most specific file is used, with the following precedence:
.env.<environment-name>.local (most specific)
.env.local
.env.<environment-name>
.env (least specific)

Controlling `.env` handling

It is possible to control how .env files are loaded in local development by setting environment variables on the process running the tools.

To disable loading local dev vars from .env files without providing a .dev.vars file, set the CLOUDFLARE_LOAD_DEV_VARS_FROM_DOT_ENV environment variable to "false".
To include every environment variable defined in your system's process environment as a local development variable, ensure there is no .dev.vars and then set the CLOUDFLARE_INCLUDE_PROCESS_ENV environment variable to "true". This is not needed when using the secrets configuration property, which loads from process.env automatically.

Module Aliasing

Note

If you're using the Cloudflare Vite plugin, alias is replaced Vite's resolve.alias ↗︎.

You can configure Wrangler to replace all calls to import a particular package with a module of your choice, by configuring the alias field:

{
    "alias": {
        "foo": "./replacement-module-filepath",
    },
}

[alias]
foo = "./replacement-module-filepath"

replacement-module-filepath.jsjs

export const bar = "baz";

With the configuration above, any calls to import or require() the module foo will be aliased to point to your replacement module:

import { bar } from "foo";

console.log(bar); // returns "baz"

Bundling issues

When Wrangler bundles your Worker, it might fail to resolve dependencies. Setting up an alias for such dependencies is a simple way to fix the issue.

However, before doing so, verify that the package is correctly installed in your project, either as a direct dependency in package.json or as a transitive dependency.

If an alias is the correct solution for your dependency issue, you have several options:

Alternative implementation — Implement the module's logic in a Worker-compatible manner, ensuring that all the functionality remains intact.
No-op module — If the module's logic is unused or irrelevant, point the alias to an empty file. This makes the module a no-op while fixing the bundling issue.
Runtime error — If the module's logic is unused and the Worker should not attempt to use it (for example, because of security vulnerabilities), point the alias to a file with a single top-level throw statement. This fixes the bundling issue while ensuring the module is never actually used.

Example: Aliasing dependencies from NPM

You can use module aliasing to provide an implementation of an NPM package that does not work on Workers — even if you only rely on that NPM package indirectly, as a dependency of one of your Worker's dependencies.

For example, some NPM packages depend on node-fetch ↗︎, a package that provided a polyfill of the fetch() API, before it was built into Node.js.

node-fetch isn't needed in Workers, because the fetch() API is provided by the Workers runtime. And node-fetch doesn't work on Workers, because it relies on currently unsupported Node.js APIs from the http/https modules.

You can alias all imports of node-fetch to instead point directly to the fetch() API that is built into the Workers runtime:

{
    "alias": {
        "node-fetch": "./fetch-polyfill",
    },
}

[alias]
node-fetch = "./fetch-polyfill"

./fetch-polyfilljs

export default fetch;

Example: Aliasing Node.js APIs

You can use module aliasing to provide your own polyfill implementation of a Node.js API that is not yet available in the Workers runtime.

For example, let's say the NPM package you rely on calls fs.readFile ↗︎. You can alias the fs module by adding the following to your Worker's Wrangler configuration file:

{
    "alias": {
        "fs": "./fs-polyfill",
    },
}

[alias]
fs = "./fs-polyfill"

./fs-polyfilljs

export function readFile() {
    // ...
}

In many cases, this allows you to work provide just enough of an API to make a dependency work. You can learn more about Cloudflare Workers' support for Node.js APIs on the Cloudflare Workers Node.js API documentation page.

Source maps

Source maps translate compiled and minified code back to the original code that you wrote. Source maps are combined with the stack trace returned by the JavaScript runtime to present you with a stack trace.

Source maps are uploaded by default for JavaScript and TypeScript Workers. Frameworks and custom builds must also generate maps.

upload_source_maps boolean optional
Controls whether Wrangler generates and uploads source map files when you run wrangler deploy, wrangler versions upload, or wrangler preview.
When unset, Wrangler uploads source maps and skips any it cannot resolve. This is the default from Wrangler 4.150.0. Earlier versions only upload source maps when this is set to true.
When set to true, Wrangler fails the upload if a source map cannot be resolved.
When set to false, Wrangler does not upload source maps.

Example:

{
    "upload_source_maps": false,
}

upload_source_maps = false

Workers Sites

Use Workers Static Assets Instead

You should use Workers Static Assets to host full-stack applications instead of Workers Sites. It has been deprecated in Wrangler v4, and the Cloudflare Vite plugin does not support Workers Sites. Do not use Workers Sites for new projects.

Workers Sites allows you to host static websites, or dynamic websites using frameworks like Vue or React, on Workers.

bucket string required
The directory containing your static assets. It must be a path relative to your Wrangler configuration file.
include string[] optional
An exclusive list of .gitignore-style patterns that match file or directory names from your bucket location. Only matched items will be uploaded.
exclude string[] optional
A list of .gitignore-style patterns that match files or directories in your bucket that should be excluded from uploads.

Example:

{
    "site": {
        "bucket": "./public",
        "include": ["upload_dir"],
        "exclude": ["ignore_dir"],
    },
}

[site]
bucket = "./public"
include = [ "upload_dir" ]
exclude = [ "ignore_dir" ]

Proxy support

Corporate networks will often have proxies on their networks and this can sometimes cause connectivity issues. To configure Wrangler with the appropriate proxy details, add the following environmental variables:

https_proxy
HTTPS_PROXY
http_proxy
HTTP_PROXY

To configure this on macOS, add HTTP_PROXY=http://<YOUR_PROXY_HOST>:<YOUR_PROXY_PORT> before your Wrangler commands.

Example:

$ HTTP_PROXY=http://localhost:8080 wrangler dev

If your IT team has configured your computer's proxy settings, be aware that the first non-empty environment variable in this list will be used when Wrangler makes outgoing requests.

For example, if both https_proxy and http_proxy are set, Wrangler will only use https_proxy for outgoing requests.

Source of truth

We recommend treating your Wrangler configuration file as the source of truth for your Worker configuration, and to avoid making changes to your Worker via the Cloudflare dashboard if you are using Wrangler.

If you need to make changes to your Worker from the Cloudflare dashboard, the dashboard will generate a TOML snippet for you to copy into your Wrangler configuration file, which will help ensure your Wrangler configuration file is always up to date.

If you change your environment variables in the Cloudflare dashboard, Wrangler will override them the next time you deploy. If you want to disable this behavior, add keep_vars = true to your Wrangler configuration file.

If you change your routes in the dashboard, Wrangler will override them in the next deploy with the routes you have set in your Wrangler configuration file. To manage routes via the Cloudflare dashboard only, remove any route and routes keys from your Wrangler configuration file. Then add workers_dev = false to your Wrangler configuration file. For more information, refer to Deprecations.

Wrangler will not delete your secrets (encrypted environment variables) unless you run wrangler secret delete <key>.

Generated Wrangler configuration

Note

This section describes a feature that can be implemented by frameworks and other build tools that are integrating with Wrangler.

It is unlikely that an application developer will need to use this feature, but it is documented here to help you understand when Wrangler is using a generated configuration rather than the original, user's configuration.

For example, when using the Cloudflare Vite plugin, an output Worker configuration file is generated as part of the build. This is then used for preview and deployment.

Some framework tools, or custom pre-build processes, generate a modified Wrangler configuration to be used to deploy the Worker code. In this case, the tool may also create a special .wrangler/deploy/config.json file that redirects Wrangler to use the generated configuration rather than the original, user's configuration.

Wrangler uses this generated configuration only for the following deploy and dev related commands:

wrangler deploy
wrangler dev
wrangler versions upload
wrangler versions deploy
wrangler pages deploy
wrangler pages functions build

When running these commands, Wrangler looks up the directory tree from the current working directory for a file at the path .wrangler/deploy/config.json. This file must contain only a single JSON object of the form:

{ "configPath": "../../path/to/wrangler.jsonc" }

When this config.json file exists, Wrangler will follow the configPath (relative to the .wrangler/deploy/config.json file) to find the generated Wrangler configuration file to load and use in the current command. Wrangler will display messaging to the user to indicate that the configuration has been redirected to a different file than the user's configuration file.

The generated configuration file should not include any environments. This is because such a file, when required, should be created as part of a build step, which should already target a specific environment. These build tools should generate distinct deployment configuration files for different environments.

Configuration (17)·续5

Configuration (17)·续5

Secrets

secrets configuration property

Local development

Module Aliasing

Bundling issues

Example: Aliasing dependencies from NPM

Example: Aliasing Node.js APIs

Source maps

Workers Sites

Proxy support

Source of truth

Generated Wrangler configuration

Custom build tool example

`secrets` configuration property