configuration

366 notes in this subject, read out of this brain and free to use. This is page 1 of 7.

Enable nodejs_compat flag

The nodejs_compat compatibility flag gives your Worker access to Node.js built-in modules like node:crypto, node:buffer, node:stream, and others. Many libraries depend on these modules, and enabling this flag avoids cryptic import errors at runtime.

Keep compatibility_date current

The compatibility_date controls which runtime features and bug fixes are available to your Worker. Setting it to today's date on new projects ensures you get the latest behavior. Periodically updating it on existing projects gives you access to new APIs and fixes without changing your code.

Store secrets with wrangler secret put, not in source

Secrets (API keys, tokens, database credentials) must never appear in your Wrangler configuration or source code. Use wrangler secret put to store them securely, and access them through env at runtime. For local development, use a .env file and ensure it is in your .gitignore. Non-secret configuration should live in version control using the vars field.

Configure environments deliberately

Wrangler environments let you deploy the same code to separate Workers for production, staging, and development. Each environment creates a distinct Worker named {name}-{env}. Each environment is treated separately: bindings and vars need to be declared per environment and are not inherited. The root Worker (without an environment suffix) is a separate deployment. If you do not intend to use it, do not deploy without specifying an environment using --env.

Generate Env types with wrangler types command

Do not hand-write your Env interface. Run wrangler types to generate a type definition file that matches your actual Wrangler configuration. This catches mismatches between your config and code at compile time instead of at deploy time. Re-run wrangler types whenever you add or rename a binding.

Wrangler Environments setup with Workers Builds

To use Wrangler Environments with Workers Builds: (1) Deploy via wrangler to create Workers for your environments on the Dashboard if you do not already have them; (2) Find the Workers for your environments, typically named '[name of Worker] - [environment name]'; (3) Connect your repository to each of the Workers for your environment; (4) In each Worker, edit your Wrangler commands to include the flag '--env <environment name>' in the build configurations for both the deploy command and the non-production branch deploy command. When a new commit is detected in the repository, a new build/deploy will trigger for each associated Worker.

Wrangler Environments example with staging and production

Example: Create a Worker named 'my-worker' with two environments 'staging' and 'production' defined in wrangler.jsonc. Deploy using 'wrangler deploy --env staging' and 'wrangler deploy --env production'. In the Cloudflare Dashboard, find the two Workers named 'my-worker-staging' and 'my-worker-production'. Connect the Git repository for 'my-worker' to both environment Workers. Edit the deploy commands to 'npx wrangler deploy --env staging' and 'npx wrangler deploy --env production' respectively. Edit the non-production branch deploy commands to 'npx wrangler versions upload --env staging' and 'npx wrangler versions upload --env production' respectively.

Monorepo setup steps for Workers Builds

To set up a monorepo workflow with Workers Builds: (1) Find the Workers associated with your project in the Workers & Pages Dashboard; (2) Connect your monorepo to each Worker in the repository; (3) Set the root directory for each Worker to specify the location of its wrangler.jsonc and where build and deploy commands should run; (4) Optionally configure unique build and deploy commands for each Worker; (5) Optionally configure build watch paths for each Worker to monitor specific paths for changes. When a new commit is made, a new build and deploy will trigger for each Worker if the change is within its included watch paths.

Benefits of merging configuration PR

Without the configuration in your repository, every build runs autoconfig first, which means your project gets built twice - once during autoconfig to generate the configuration, and again for the actual deployment. Merging the PR commits the configuration to your repository, so future builds skip autoconfig and go straight to building and deploying, resulting in faster deployments and version-controlled settings.

Name conflict PR resolution

The name conflict PR will update the name field in your Wrangler configuration to match the Worker name in the Cloudflare dashboard.

Name conflict PR creation

If Workers Builds detects a mismatch between your Worker name in the Cloudflare dashboard and the name field in your Wrangler configuration file, it will create a pull request to fix the conflict. This can happen when you rename your Worker in the dashboard but not in your config file, when you connect a repository that was previously used with a different Worker, or when the name field in your config does not match the connected Worker.

Command detection after PR merge

When you merge a configuration PR, Workers Builds will update your build and deploy commands if they do not match the detected settings, ensuring successful deployments.

Configuration PR creation conditions

Workers Builds automatically creates a configuration PR when you connect a repository without a Wrangler configuration file and your deploy command is 'npx wrangler deploy'. If you have a custom deploy command, autoconfig will still run and configure your project, but no PR will be created.

Configuration PR files and changes

The configuration PR may contain changes to: wrangler.jsonc (Wrangler configuration file), framework adapter (such as @astrojs/cloudflare for Astro), framework configuration (such as astro.config.mjs or svelte.config.js), package.json (new scripts like deploy, preview, cf-typegen, plus dependencies), package-lock.json / yarn.lock / pnpm-lock.yaml (updated lock file), .gitignore (entries for .wrangler and .dev.vars* files), and .assetsignore (for frameworks that generate worker files in output directory).

PR review workflow

When you receive a PR from Workers Builds: review the changes to check that the configuration matches your project requirements; test the preview using the preview link in the PR description to verify everything works; merge when ready to enable faster deployments.

Configuration PR description contents

The PR description includes: detected settings (framework, build command, deploy command, version command), preview link (a working preview generated using detected settings), and next steps (links to documentation for adding bindings, custom domains, and more).

Package managers supported for dependency caching

Workers build cache supports the following package managers and caches their global cache directories: npm caches .npm; yarn caches .cache/yarn; pnpm caches .pnpm-store; bun caches .bun/install/cache.

Build cache automatically detects package manager and framework

When enabled, Workers build cache automatically detects which package manager and framework the project is using from its package.json and caches data accordingly for the build.

Frameworks supported for build output caching

Workers Builds automatically detects and caches framework build output directories for: Astro (.astro under node_modules), Docusaurus (node_modules/.cache, .docusaurus, build), Eleventy (.cache), Gatsby (.cache, public), Next.js (.next/cache), Nuxt (node_modules/.cache/nuxt), SvelteKit (node_modules/.cache/imagetools).

Build cache behavior on first and subsequent builds

The first build to occur after enabling build caching on a Workers project will save relevant artifacts to cache. Every subsequent build will restore from cache unless configured otherwise.

Clear build cache in Workers dashboard

To clear the build cache, navigate to Workers & Pages Overview on the Dashboard, find the Workers project, go to Settings > Build > Build cache, and select Clear Cache to clear the build cache.

Enable build cache in Workers dashboard

To enable build caching, navigate to Workers & Pages Overview on the Dashboard, find the Workers project, go to Settings > Build > Build cache, and select Enable to turn on build caching.

Override default versions in Workers Builds using environment variables or files

Default versions can be overridden using build environment variables or version files in the source code root directory. For Go, use GO_VERSION environment variable. For Node.js, use NODE_VERSION environment variable or .nvmrc/.node-version files. For Python, use PYTHON_VERSION environment variable or .python-version/runtime.txt files. For Ruby, use RUBY_VERSION environment variable or .ruby-version file. For Bun, Hugo, yarn, and pnpm, use BUN_VERSION, HUGO_VERSION, YARN_VERSION, and PNPM_VERSION environment variables respectively. Version files should contain only the version number.

Workers Builds default runtime versions

Workers Builds uses the following default runtime versions unless overridden: Go 1.24.3, Node.js 24.18.0, Python 3.13.3, and Ruby 3.4.4. The build image also preinstalls Node.js 22.23.2 and 24.18.0.

Skip automatic dependency installation in Workers Builds

Set the build variable SKIP_DEPENDENCY_INSTALL to 1 or true to disable automatic dependency installation and run a custom install command instead.

Workers Builds default tools and package manager versions

Workers Builds includes the following default tool versions: Bun 1.2.15, Hugo extended_0.147.7, npm 10.9.2, yarn 4.9.1, pnpm 10.11.1, pip 25.1.1, gem 3.6.9, poetry 2.1.3, pipx 1.7.1, and bundler 2.6.9.

Avoid unexpected Workers Builds failures best practice

Monitor announcements via the Cloudflare Changelog, dashboard notifications, and email. Pin specific versions of critical preinstalled software by overriding default versions to maintain a specific version and avoid automatic updates.

Pre-installed packages in Workers Builds

The Workers Builds image includes the following pre-installed packages installed via apt: curl, libbz2-dev, libreadline-dev, git, libc++1, libssl-dev, git-lfs, libdb-dev, libvips-dev, unzip, libgdbm-dev, libyaml-dev, autoconf, libgdbm6, tzdata, build-essential, libgbm1, wget, bzip2, libgmp-dev, zlib1g-dev, gnupg, liblzma-dev, zstd, libffi-dev, and libncurses5-dev.

Workers Builds preinstalled software update policy

Preinstalled software is updated before reaching end-of-life. Minor version updates may be applied without notice to the latest available minor version, unless a default version has been overridden. Major version updates are applied to the next stable long-term support (LTS) version with 3 months' notice. Tools that do not follow semantic versioning (such as Bun or Hugo) will receive 3 months' notice for updates that may contain breaking changes. Notifications are provided via the Cloudflare Changelog, dashboard notifications for affected projects, and email notifications to project owners.

Find build by version ID API

Use GET /builds/builds?version_ids={version_id} to find the build associated with a specific version. Example: curl -s "https://api.cloudflare.com/client/v4/accounts/{account_id}/builds/builds?version_ids={version_id}" --header "Authorization: Bearer <API_TOKEN>" | jq '.result.builds'. From the response, note trigger.trigger_uuid, build_trigger_metadata.branch, and build_trigger_metadata.commit_hash for redeployment.

Trigger build with branch and commit

When triggering a build, you can specify branch, commit_hash, or both. If only commit_hash is provided without branch, it builds the commit on its current branch. Passing both branch and commit_hash pins the build to that exact commit on that branch.

Create preview trigger API

Use POST /builds/triggers to create a preview trigger for non-production branches. Example: curl -s "https://api.cloudflare.com/client/v4/accounts/{account_id}/builds/triggers" --header "Authorization: Bearer <API_TOKEN>" --header "Content-Type: application/json" --request POST --data '{"external_script_id": "<WORKER_TAG>", "repo_connection_uuid": "<REPO_CONNECTION_UUID>", "build_token_uuid": "<BUILD_TOKEN_UUID>", "trigger_name": "Deploy preview branches", "build_command": "npm run build", "deploy_command": "npx wrangler versions upload", "root_directory": "/", "branch_includes": ["*"], "branch_excludes": ["main"], "path_includes": ["*"], "path_excludes": []}'. Note: preview uses 'npx wrangler versions upload' instead of 'npx wrangler deploy'.

Create production trigger API

Use POST /builds/triggers to create a production trigger. Example: curl -s "https://api.cloudflare.com/client/v4/accounts/{account_id}/builds/triggers" --header "Authorization: Bearer <API_TOKEN>" --header "Content-Type: application/json" --request POST --data '{"external_script_id": "<WORKER_TAG>", "repo_connection_uuid": "<REPO_CONNECTION_UUID>", "build_token_uuid": "<BUILD_TOKEN_UUID>", "trigger_name": "Deploy production", "build_command": "npm run build", "deploy_command": "npx wrangler deploy", "root_directory": "/", "branch_includes": ["main"], "branch_excludes": [], "path_includes": ["*"], "path_excludes": []}'.

Create repository connection API

Use PUT /builds/repos/connections to create a connection between a GitHub repository and Cloudflare. Example: curl -s "https://api.cloudflare.com/client/v4/accounts/{account_id}/builds/repos/connections" --header "Authorization: Bearer <API_TOKEN>" --header "Content-Type: application/json" --request PUT --data '{"provider_type": "github", "provider_account_id": "<GITHUB_USER_ID>", "provider_account_name": "<GITHUB_USERNAME>", "repo_id": "<GITHUB_REPO_ID>", "repo_name": "<REPO_NAME>"}'. Response includes repo_connection_uuid for creating triggers.

Set up Builds from scratch prerequisites

Before using the Builds API to set up Workers Builds, you must first install the Cloudflare GitHub App through the dashboard. Go to Workers & Pages, select any Worker, go to Settings > Builds > Connect, select GitHub, and authorize the Cloudflare GitHub App for your account or organization. This one-time setup creates the connection between GitHub and Cloudflare.

Purge build cache API

Use POST /builds/triggers/{trigger_uuid}/purge_build_cache to clear cached dependencies and build artifacts for a trigger. Example: curl -s "https://api.cloudflare.com/client/v4/accounts/{account_id}/builds/triggers/{trigger_uuid}/purge_build_cache" --header "Authorization: Bearer <API_TOKEN>" --request POST.

Set build environment variables API

Use PATCH /builds/triggers/{trigger_uuid}/environment_variables to set environment variables for a trigger. Example: curl -s "https://api.cloudflare.com/client/v4/accounts/{account_id}/builds/triggers/{trigger_uuid}/environment_variables" --header "Authorization: Bearer <API_TOKEN>" --header "Content-Type: application/json" --request PATCH --data '{"NODE_ENV": {"value": "production", "is_secret": false}, "API_KEY": {"value": "prod-secret-key", "is_secret": true}}'. Set is_secret to false for plain values and true for sensitive values masked in logs.

List build environment variables API

Use GET /builds/triggers/{trigger_uuid}/environment_variables to list environment variables for a trigger. Example: curl -s "https://api.cloudflare.com/client/v4/accounts/{account_id}/builds/triggers/{trigger_uuid}/environment_variables" --header "Authorization: Bearer <API_TOKEN>".

Build environment variables are build-time only

Environment variables set via the Builds API are available only during the build process, not at runtime. These are build-time environment variables. For runtime environment variables, refer to the Environment variables documentation.

"Resource not found" error troubleshooting

If you receive a "Resource not found" error, you are likely using the Worker name instead of the Worker tag. The Builds API requires the tag (a UUID like '1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d'), not the Worker name.

Cancel build API

Use PUT /builds/builds/{build_uuid}/cancel to cancel a running build. Example: curl -s "https://api.cloudflare.com/client/v4/accounts/{account_id}/builds/builds/{build_uuid}/cancel" --header "Authorization: Bearer <API_TOKEN>" --request PUT. The build_uuid can come from listing builds, triggering a build response, or the last segment of the build details URL in the dashboard.

Get build logs API

Use GET /builds/builds/{build_uuid}/logs to retrieve build logs. Example: curl -s "https://api.cloudflare.com/client/v4/accounts/{account_id}/builds/builds/{build_uuid}/logs" --header "Authorization: Bearer <API_TOKEN>". The build_uuid can come from listing builds, triggering a build response, or the last segment of the build details URL in the dashboard.

List builds for Worker API

Use GET /builds/workers/{worker_tag}/builds to list builds for a Worker. Example: curl -s "https://api.cloudflare.com/client/v4/accounts/{account_id}/builds/workers/{worker_tag}/builds" --header "Authorization: Bearer <API_TOKEN>" | jq '.result[] | {build_uuid, status, branch, created_at}'. Response includes build_uuid which is needed for getting logs or canceling builds.

Trigger manual build API

To trigger a manual build, POST to /builds/triggers/{trigger_uuid}/builds with a JSON body containing branch, commit_hash, or both. Example: curl -s "https://api.cloudflare.com/client/v4/accounts/{account_id}/builds/triggers/{trigger_uuid}/builds" --header "Authorization: Bearer <API_TOKEN>" --header "Content-Type: application/json" --request POST --data '{"branch": "main"}'. Response includes build_uuid for monitoring.

Get trigger UUID API example

Example curl command to list triggers for a Worker: curl -s "https://api.cloudflare.com/client/v4/accounts/{account_id}/builds/workers/{worker_tag}/triggers" --header "Authorization: Bearer <API_TOKEN>" | jq '.result[] | {trigger_uuid, trigger_name, branch_includes, branch_excludes}'. Returns trigger objects with trigger_uuid, trigger_name, branch_includes array, and branch_excludes array.

Update trigger configuration API

Use PATCH /builds/triggers/{trigger_uuid} to update trigger fields. Example: curl -s "https://api.cloudflare.com/client/v4/accounts/{account_id}/builds/triggers/{trigger_uuid}" --header "Authorization: Bearer <API_TOKEN>" --header "Content-Type: application/json" --request PATCH --data '{"build_command": "npm run build:prod", "deploy_command": "npx wrangler deploy"}'. You can update any trigger field like build_command, deploy_command, branch_includes, etc.

Get Worker tag API example

Example curl command to list all Workers and retrieve their tags: curl -s "https://api.cloudflare.com/client/v4/accounts/{account_id}/workers/scripts" --header "Authorization: Bearer <API_TOKEN>" | jq '.result[] | {name: .id, tag: .tag}'. Returns objects with name (e.g. 'my-worker') and tag (e.g. '1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d').

Builds API workflow overview

The standard workflow is: Step 1 - Get Worker tag via GET /workers/scripts; Step 2 - Get trigger UUID via GET /builds/workers/:worker_tag/triggers; Step 3a - Trigger build via POST /builds/triggers/:trigger_uuid/builds; Step 3b - List builds via GET /builds/workers/:worker_tag/builds; Step 3c - Get logs via GET /builds/builds/:build_uuid/logs; Step 3d - Cancel build via PUT /builds/builds/:build_uuid/cancel.

Build token vs API token

A build token is different from an API token. The API token (user-scoped) is used to call the Builds API itself. A build token is used by the build system to deploy the Worker and is identified by a build_token_uuid, found in the Worker's Settings > Builds > API token section.

Delete build environment variable API

Use DELETE /builds/triggers/{trigger_uuid}/environment_variables/{variable_key} to delete an environment variable. Example: curl -s "https://api.cloudflare.com/client/v4/accounts/{account_id}/builds/triggers/{trigger_uuid}/environment_variables/{variable_key}" --header "Authorization: Bearer <API_TOKEN>" --request DELETE. The variable_key is the key name like 'NODE_ENV'.

Trigger fields reference

Trigger fields are: trigger_name (string, display name), build_token_uuid (string, UUID of build token), build_command (string, e.g. 'npm run build'), deploy_command (string, e.g. 'npx wrangler deploy'), root_directory (string, path to project root), branch_includes (array, branch patterns like ['main'] or ['*']), branch_excludes (array, excluded branch patterns), path_includes (array, file path patterns to trigger), path_excludes (array, file paths to ignore), build_caching_enabled (boolean, enable/disable caching), environment_variables (object, build-time variables for trigger).

Trigger definition and limits

A trigger is a configuration that defines how a Worker gets built and deployed, specifying the build command, deploy command, environment variables, and which branches trigger builds. Each Worker has up to two triggers: one for production (runs on the production branch) and one for preview (runs on all other branches).

Worker tag vs Worker name

The Builds API identifies Workers by their tag, an immutable UUID assigned by Cloudflare (documented as external_script_id), not by the Worker name. The Worker name (id) is a string like 'my-worker', while the tag is a UUID like '1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d'. Every Builds API endpoint that references a Worker requires the tag, not the name.

Get build token UUID API

Use GET /builds/tokens to list build tokens. Example: curl -s "https://api.cloudflare.com/client/v4/accounts/{account_id}/builds/tokens" --header "Authorization: Bearer <API_TOKEN>" | jq '.result[] | {build_token_uuid, build_token_name}'. Alternatively, find the build token UUID in the Worker's Settings > Builds > API token section in the dashboard.

Builds API requires user-scoped API token

The Builds API requires a user-scoped API token for authentication. Account-scoped tokens are not supported and will return "Invalid token" errors. The token must have "Workers Builds Configuration" with Edit access and "Workers Scripts" with Read access.

Redeploy current deployment with same commit

To redeploy your current active deployment with the same branch and commit (useful to rebuild without code changes), use POST /builds/triggers/{trigger_uuid}/builds with both branch and commit_hash from the current deployment's build. Example: curl -s "https://api.cloudflare.com/client/v4/accounts/{account_id}/builds/triggers/{trigger_uuid}/builds" --header "Authorization: Bearer <API_TOKEN>" --header "Content-Type: application/json" --request POST --data '{"branch": "{branch}", "commit_hash": "{commit_hash}"}'.

Get active deployment version ID API

Use GET /workers/scripts/{script_name}/deployments to get the active deployment's version ID. Example: curl -s "https://api.cloudflare.com/client/v4/accounts/{account_id}/workers/scripts/{worker_name}/deployments" --header "Authorization: Bearer <API_TOKEN>" | jq '.result.deployments[0].versions[0].version_id'. Use the worker_name from Step 1 (the Worker's id/name field, not the tag).

Build watch paths default configuration

Workers defaults to setting a project's includes paths to everything ([*]) and excludes paths to nothing ([]).

Build watch paths configuration location

To configure build watch paths for a Workers project, navigate to the project Overview, then go to Settings > Build > Build watch paths.

Build watch paths evaluation order

For each path in a push event, build watch paths are evaluated as follows: paths satisfying excludes conditions are ignored first, any remaining paths are checked against includes conditions, and if any matching path is found, a build is triggered. Otherwise the build is skipped.

Give your agent this brain