---
public-agent: true
id: wrangler-configuration
title: Wrangler Configuration Standard
status: current
classification: public-agent-standard
safety: reviewed-public
---

# Wrangler Configuration Standard

This standard covers repository ownership of Cloudflare Worker configuration
in `wrangler.jsonc`. Cloudflare documents the supported fields and their
runtime/deployment semantics in its [Wrangler configuration
reference](https://developers.cloudflare.com/workers/wrangler/configuration/).
Meridian policy distinguishes authored intent, generated configuration and
live provider state.

Wrangler JSONC files may use this compact reference comment near the top:

```jsonc
// Public standard: https://agents.meridianstack.dev/standards/wrangler-configuration
```

## Source ownership

Treat an authored Wrangler file as deployable configuration only when the
repository's deployment contract identifies it as such. Where Meridian Config
generates `wrangler.jsonc`, edit its canonical Config inputs, regenerate the
deterministic, non-secret file, **commit that generated projection alongside
its inputs**, and check for drift in CI. Treat it like a lockfile, not an
editable independent authority. Generated `.wrangler/types/*.d.ts`, local
Wrangler overrides and `.dev.vars*` remain untracked; do not hand-edit
generated files. A deliberately authored Wrangler file remains independently
source-owned. The generator and its configuration contract own precedence
and defaults.

Wrangler's configuration is the source of truth for the Worker configuration
that Wrangler reads. Meridian's provider and deployment configuration may own
additional repository intent such as target selection, generated-file paths,
build commands and reconciliation metadata. Those inputs are not interchangeable
with observed provider state. A successful local config check also does not
prove that a deployed Worker matches it.

## Bindings and values

Use bindings for runtime services and resources, and `vars` for non-sensitive
configuration. Never place credentials or sensitive values in committed
configuration or plain-text `vars`. Declare required secret names when the
supported Wrangler version and deployment contract use that facility; supply
secret values through the approved local or provider secret boundary. Cloudflare
documents [Worker secrets](https://developers.cloudflare.com/workers/configuration/secrets/)
and warns against storing sensitive information in `vars`.

Bindings, environments, migrations, asset directories, compatibility settings
and resource identifiers vary by Worker. Preserve intentional project-local
configuration instead of filling templates with placeholder resources. Use
explicit local overrides only when a runtime or environment needs a different
binding contract, and keep generated type declarations aligned with the
effective configuration.

## Default Worker runtime posture

Classify each deployed Worker by actual workload before configuring it: authenticated
API/admin, public dynamic web, assets-first/static, scheduled/queue processor, or
provider/infrastructure service. A single named profile may be reused across
deployables with matching security and cost characteristics, but it does not
override route-specific caching or security requirements.

For active Workers with an executable runtime, prefer native Cloudflare Workers
Issues when supported by the repository-pinned Wrangler schema. Author
`observability.issues.enabled: true` inside the existing `observability`
configuration, preserving any configured invocation logs, persistent log and
trace destinations, and redaction controls. Do not add unsupported schema keys
to older Wrangler versions: upgrade and validate the pinned toolchain first.
For static-assets-only deployments, document whether Worker Issues provides
useful runtime evidence rather than assuming static requests execute a Worker.
The workspace currently pins Wrangler 4.149.0, which supports this setting.
[Wrangler 4.150.0 changes deploys to upload source maps by
default](https://github.com/cloudflare/workers-sdk/releases/tag/wrangler@4.150.0);
adopting that separate deployment behavior needs its own review rather than
being bundled into the Issues baseline.

Meridian's current source profiles are `control-plane-api`, `queue-workflow`,
`assets-site`, and `client-workspaces-gateway`. The profile names describe
workload; they do not assert the deployed access perimeter or replace
target-specific bindings, routes, authentication, or runtime settings. The
canonical provider config is authoritative for generated targets. The separate
Client Workspaces gateway keeps its authored Wrangler file.

| Worker | Workload | Issues | Compatibility date | Source posture |
| --- | --- | --- | --- | --- |
| Agent Operations | API, Queue consumer and Workflow | Enabled | `2026-06-05` | `queue-workflow`; shared logs/traces defaults |
| Agent Gateway | API gateway | Enabled | `2026-06-05` | `control-plane-api`; shared logs/traces defaults |
| Build Radar | API, Queue consumer and scheduled handler | Enabled | `2026-06-05` | `queue-workflow`; shared logs/traces defaults |
| Database Catalogue | Control-plane API | Enabled | `2026-06-05` | `control-plane-api`; shared logs/traces defaults |
| Managed Repository Assessment | Control-plane API and Workflow processing | Enabled | `2026-06-05` | `control-plane-api`; shared logs/traces defaults |
| Software Inventory | Control-plane API | Enabled | `2026-06-05` | `control-plane-api`; shared logs/traces defaults |
| Credential Catalogue | Control-plane API | Enabled | `2026-06-05` | `control-plane-api`; shared logs/traces defaults |
| Configuration Assurance | Control-plane API | Enabled | `2026-06-05` | `control-plane-api`; shared logs/traces defaults |
| Meridian Docs | Website Worker with static assets | Enabled | `2026-06-05` | `assets-site`; executable fallback handler |
| Agent Standards | Static-assets-only site | Disabled | `2026-06-05` | `assets-site`; no authored Worker handler |
| App UI Storybook | Static-assets-only site | Disabled | `2026-08-16` | `assets-site`; no authored Worker handler |
| Client Workspaces Gateway | Access-assertion gateway with R2 binding | Enabled | `2026-09-07` | `client-workspaces-gateway`; authored config |

For generated Worker targets, the shared provider defaults keep persisted logs
and invocation logs enabled at 100% sampling and persisted traces enabled at
25%, with the existing `meridian-grafana-logs` and `meridian-grafana-traces`
destinations. The two assets-only targets explicitly opt out of Issues because
they have no authored JavaScript handler whose failures the feature could
group. Meridian Docs has a Worker entrypoint and stays in the Issues profile.
Revisit these exceptions if either static-only target gains runtime code. These
source classifications do not establish whether a route is publicly reachable
or protected by Cloudflare Access; the live access perimeter is **unknown**.
The current 100% log and 25% trace sampling values are preserved from source;
event volumes, destination ingestion and resulting costs have not been measured.
Review those values against observed workload volume and current billing before
changing them.

The shared `2026-06-05` date, App UI's `2026-08-16` date, and Client Workspaces'
`2026-09-07` date remain at the tested source values; this change does not
advance compatibility. Generated targets inherit `nodejs_compat` except
Meridian Docs, whose source explicitly clears the flag; this change preserves
both settings. A date or flag change requires target-package regression
evidence before it is accepted. No canonical target currently declares a CPU
limit, placement override, or enabled Workers runtime cache. Runtime cache remains off by
omission: do not add `cache.enabled: true` without endpoint-specific response
safety, cache-key/TTL/invalidation evidence, and a request-cost comparison.
Cloudflare charges the normal Workers request rate for cache hits and for
requests that otherwise would be free, including static assets and service
binding calls; a hit avoids Worker CPU execution but does not make the request
free. See [Workers Cache pricing](https://developers.cloudflare.com/workers/cache/).

The repository declares hosted Workers Builds targets, but this source audit
does not establish the live trigger value of `build_caching_enabled`. That
provider state is **unknown**. Keep frozen-lockfile installation and narrow
watch paths as the source-side reproducibility baseline. Read the trigger with
an approved read-only provider path before deciding whether to enable or
disable its cache; do not infer it from a successful build or this Wrangler
configuration. The Client Workspaces gateway uses the existing Grafana
destination names from Meridian's canonical defaults, while their live
availability for that Worker remains **unknown**.

Use service-specific sampling levels. High-value queue/retry/ingress diagnostics
may need greater log and trace coverage than high-volume public content;
sampling should be changed on observed event volume and actual cost, not a
global percentage copied between repositories. Structured logs must exclude
authentication headers, secrets, raw private payloads and unbounded provider
responses. Cloudflare Issues, sampled logs and traces are diagnostics, not
authoritative D1/Queue/Workflow execution counts or proof of Grafana delivery.

## Runtime cache versus build cache

Leave the Workers **runtime cache disabled by default** on authenticated,
tenant-specific, mutable or service-bound endpoints. Evaluate opt-in caching
only with proven public-response safety, explicit cache keys, TTL/invalidation
and comparison of request charges. Runtime Workers Cache can change the billable
request class for traffic including static assets and service bindings; it is
not a free generic performance switch. Do not confuse it with ordinary static
asset/CDN caching or application-level caching.

Cloudflare **Workers Builds caching** is configured on the hosted build trigger,
not through the Worker runtime `wrangler.jsonc` cache setting. Inspect the
provider's `build_caching_enabled` state with a reviewed, read-only provider
tool and preserve reproducible frozen package installs, build roots and
path-scoped watch paths. Repository build intent is not evidence of current
hosted trigger state. Provider caching may require a separately reviewed
reconciliation operation when drift is demonstrated.

## Compatibility, limits and rollout

Keep tested `compatibility_date` values until the affected Worker packages
and APIs have been regression-tested with a specific proposed date. Keep
`nodejs_compat` where an older date or tested runtime needs it, and remove
redundant flags only after supported version and behaviour are verified.
Do not drive compatibility changes by the calendar alone.

Leave CPU limits and placement at documented provider defaults unless measured
CPU cost, request patterns, subrequest budget or workload behaviour justifies
a target-specific override. Long external I/O waits and CPU execution are
different cost/safety questions. If a Worker has elevated limits, retain them
until the controlling operation has credible bounded load and timeout evidence.

A successful configuration check proves authored/derived consistency, not
that the serving version or provider account matches it. Verify generated
Wrangler output against canonical Meridian Config, preserve bindings/routes/
secrets references and environment settings, inspect CI evidence, and keep
deployment creation, serving version, runtime health, Issues activation and
provider build-cache read-back as distinct outcomes. Record unknown provider
state as **unknown**, not disabled or healthy.

## Validation and exceptions

Validate the config with the repository's pinned Wrangler tooling and its
repository-owned non-mutating drift check, when available. A check validates a
local declaration; it does not grant provider access or establish live state.
Keep account-specific values, Worker names, secrets and private deployment
details out of portable guidance. Document unusual configuration where its
purpose is not clear from the owning Config or application contract.

The repository pins Wrangler to a version that supports
`observability.issues.enabled`; its installed JSON schema is the local source of
truth for config validation. Repository policy checks cover the declared
Worker inventory, required Issues posture, the documented assets-only
exceptions, preserved logs/traces settings, compatibility dates and flags,
runtime-cache opt-ins, CPU limits, and placement overrides. A new exception
must be recorded here and in the source-level policy test before it is used.
