/workers-best-practices

Workers Configuration and Observability

Use the project's Wrangler configuration and installed node_modules/wrangler/config-schema.json to check fields and binding declarations. Consult current product docs when a field or compatibility requirement needs verification. Doc paths below are relative to https://developers.cloudflare.com.

• Configuration: compatibility dates, Node.js compatibility, generated types, secrets, and config format
• Binding consistency: configuration and code agree
• Observability: enable logs and traces, configure sampling, and emit structured logs

Configuration

Keep compatibility_date current

Set compatibility_date to today on new projects. Encourage periodic updates on existing projects to adopt new runtime behavior and fixes. Review the intervening compatibility changes and run relevant tests when advancing the date.

Check: compatibility_date exists and supports the affected feature with the configured flags. Recommend updates as maintenance; flag a compatibility defect when the configured date or flags do not support the required behavior.

// wrangler.jsonc
{
  "compatibility_date": "$today",  // Replace with today's date (YYYY-MM-DD)
  "compatibility_flags": ["nodejs_compat"]
}

Retrieve: current compatibility dates at /workers/configuration/compatibility-dates/.

Enable nodejs_compat

The nodejs_compat flag enables Node.js built-in modules (node:crypto, node:buffer, node:stream). Many libraries require it. Missing this flag causes cryptic import errors at runtime.

Check: compatibility_flags includes "nodejs_compat".

{
  "compatibility_flags": ["nodejs_compat"]
}

Generate binding types with wrangler types

Never hand-write the Env interface. Run wrangler types to generate it from the wrangler config. Re-run after adding or renaming any binding.

Check: no manually defined Env or interface Env that duplicates wrangler config bindings. Look for satisfies ExportedHandler<Env> pattern on the default export.

// Generated by wrangler types — always matches actual config
export default {
  async fetch(request: Request, env: Env): Promise<Response> {
    const value = await env.MY_KV.get("key");
    return new Response(value);
  },
} satisfies ExportedHandler<Env>;

Anti-pattern:

// Hand-written Env that drifts from actual bindings
interface Env {
  MY_KV: KVNamespace;  // What if the binding name changed?
}

Store secrets with wrangler secret

Secrets must never appear in wrangler config or source code. Use wrangler secret put and access via env at runtime. Non-secret config goes in vars.

Check: no string literals that look like API keys, tokens, or credentials. Verify .env is in .gitignore for local dev.

{
  "vars": {
    "API_BASE_URL": "https://api.example.com"  // Non-secret: OK in config
  }
  // Secrets set via: wrangler secret put API_KEY
}

Anti-pattern:

{
  "vars": {
    "API_KEY": "sk-live-abc123..."  // Secret in version control
  }
}

Use wrangler.jsonc for config

Prefer wrangler.jsonc over wrangler.toml. Newer features are JSON-only. JSONC supports comments for documenting config decisions.

Check: project uses wrangler.jsonc (or wrangler.json). Flag wrangler.toml in new projects.

Binding-code consistency

For executable Worker examples, verify name, compatibility_date, and main against the target Wrangler schema.

1. Every env.X reference in code has a corresponding binding declaration in config
2. Names match exactly (case-sensitive)
3. For Durable Objects: class_name matches the exported class name

An unused binding alone is not a finding; establish a concrete configuration or runtime consequence before recommending a change.

For a new Durable Object class, verify its migration entry and exported class name against the target Wrangler schema.

Observability

Enable Workers Logs and Traces

Enable Workers Logs and Traces in Wrangler config before deploying to production. Set observability.enabled and observability.traces.enabled to true; the top-level setting alone does not enable traces. Use head_sampling_rate to control volume and cost. Use structured JSON logging — console.log(JSON.stringify({...})) — so logs are searchable. Use console.error for errors (appears at error severity in the dashboard).

Check: logs and traces are enabled in the target deployment environment, with neither disabled by an environment override. Check observability.enabled, observability.logs.enabled, and observability.traces.enabled, accounting for their defaults. Logging uses structured JSON, not string concatenation.

{
  "observability": {
    "enabled": true,
    "logs": { "enabled": true, "head_sampling_rate": 1 },
    "traces": { "enabled": true, "head_sampling_rate": 0.01 }
  }
}

// Structured JSON — searchable and filterable
console.log(JSON.stringify({ message: "incoming request", method: request.method, path: url.pathname }));

// Error severity
console.error(JSON.stringify({ message: "request failed", error: e instanceof Error ? e.message : String(e) }));

Anti-pattern:

// Unstructured string logs — hard to query
console.log("Got a request to " + url.pathname);

Retrieve: Workers Logs and Traces for current config options.