`cf_worker_config`

cf_worker_config validates and retains a Wrangler Worker configuration in memory. It does not run Wrangler or write files. cf_wrangler_dev and cf_wrangler_deploy write the configuration to a temporary wrangler.json file only while Wrangler is running.

The configuration is intentionally open-ended so new Wrangler fields can be used without an xx release. xx only requires non-empty string values for name and compatibility_date and verifies that the complete value can be encoded as JSON. Wrangler performs all other schema validation.

Relative filesystem paths are resolved from dir when the config is created because Wrangler normally resolves them from the configuration file, which xx writes outside the project. xx preserves the known main, base_dir, tsconfig, pages_build_output_dir, assets.directory, site.bucket, site.entry-point, build.cwd, build.watch_dir, wasm_modules, text_blobs, and data_blobs paths, including supported overrides below env. A custom build without cwd or watch_dir keeps Wrangler's normal defaults relative to dir. Use absolute paths for path-bearing fields not listed here.

The returned value has a name field.

Arguments

Argument	Required	Description
`config`	Yes	JSON-compatible Wrangler configuration dictionary. `name` and `compatibility_date` are required.
`dir`	No	Project-relative base directory for relative paths. Defaults to the project root. The directory is not created or checked until Wrangler uses the configuration.

Example

load("@cloudflare@1", "cf_worker_config")

worker = cf_worker_config(
    {
        "name": "api",
        "main": "src/worker.ts",
        "compatibility_date": "2026-08-18",
        "compatibility_flags": ["nodejs_compat"],
        "vars": {
            "ENVIRONMENT": "development",
        },
    },
    dir="backend/cloudflare",
)