wrangler configuration

16 notes, read out of this brain and free to use. Each one was extracted from a source and is re-checked against its exam.

Configure observability for specific environments

To configure observability for a specific environment, add the observability settings under [env.environmentname] in wrangler.jsonc, then deploy with "npx wrangler deploy -e environmentname". This allows different configurations like head_sampling_rate per environment.

Workers Logs observability configuration structure

The observability configuration in wrangler.jsonc has the structure: {"observability": {"enabled": true, "head_sampling_rate": 1}}. The head_sampling_rate field is optional with a default value of 1 (100%). All newly created Workers have observability enabled by default.

Terraform cloudflare_worker_version resource

The `cloudflare_worker_version` Terraform resource creates a version of a Worker. Required fields: `account_id`, `worker_id`, `compatibility_date` (set to today's date), `main_module` (filename of the main module), and `modules` (array of module objects). Each module object must have `name`, `content_type` (e.g., 'application/javascript+module'), and either `content_file` or `content_base64`.

Terraform cloudflare_worker resource

The `cloudflare_worker` Terraform resource creates a Worker. It requires an `account_id` and a `name`. It supports an `observability` block with an `enabled` boolean field to enable observability for the Worker.

Run cf-typegen to generate Worker environment types

After creating bindings in wrangler.json, execute 'npm run cf-typegen' to generate type definitions for your Worker environment. This provides TypeScript type safety for accessing bindings like env.DB.

Pages Functions build command and integration

For projects with a `functions/` directory, add `wrangler pages functions build --outdir=<output>/_worker.js/` to your build process. This command converts Pages Functions to Workers format. Update the main field to point to the compiled functions: `"main": "./path/to/_worker.js"`.

Use .assetsignore file to exclude _worker.js from static assets

Create a `.assetsignore` file containing `_worker.js` to prevent the worker code from being served as a static asset. Also update your build script to copy _worker.js to the output directory.

Wrangler configuration file format: prefer wrangler.jsonc

When migrating Pages projects to Workers, prefer wrangler.jsonc format for better documentation support. Convert from .toml or .json formats if currently used.

Compatibility date required in wrangler configuration

Ensure a `compatibility_date` field exists in the wrangler.jsonc configuration file when migrating from Pages to Workers.

Assets-only project wrangler configuration example

For static sites without server-side logic, use this wrangler.jsonc structure: `{"name": "my-site", "assets": {"directory": "./dist"}, "compatibility_date": "2025-06-05"}`.

Workers project with functions wrangler configuration example

For sites with server-side logic or Pages Functions, use this wrangler.jsonc structure: `{"name": "my-app", "main": "./dist/_worker.js", "assets": {"directory": "./dist", "binding": "ASSETS"}, "compatibility_date": "2025-06-05"}`.

Build script example for Pages Functions migration

For projects with Pages Functions, use this package.json build script: `"scripts": {"build": "your-framework-build && wrangler pages functions build --outdir=./dist/_worker.js/"}`.

Convert pages_build_output_dir to assets directory in wrangler.jsonc

In wrangler.jsonc configuration, replace the Pages-specific `pages_build_output_dir` field with the modern Workers Assets format: `"assets": {"directory": "path"}`.

Workers Assets configuration structure

Use the assets field in wrangler.jsonc with the format `"assets": {"directory": "./dist"}` for assets-only projects. For projects with a Workers script, add a binding: `"assets": {"directory": "./dist", "binding": "ASSETS"}`.

Detect project type by checking for Pages Functions directory

To determine if a Pages project has functions, look for a `functions/` directory containing .js or .ts files. If found, you must add `wrangler pages functions build` to your build process.

Detect project type by checking for _worker.js file

After running the build command, check the output directory for a `_worker.js` file. If it exists, you have a Workers script project and must add `"main": "./path/to/_worker.js"` and bind assets with `"binding": "ASSETS"`.

Give your agent this brain