cloudflare / cloudflare/skills

Edge HTMLRewriter mutation vs React hydration, BAA guidance, and the cf-bounce DKIM selector trap

Open
#80 0 comments 1 reaction 0 assignees View on GitHub
Dominant language
Shell
Stars
2.8k
Forks
272
Avg merge
8h 48m
Merged PRs (30d)
60

Description

Two field findings from production use of these skills, both of the "looks like a normal setup until it silently fails" shape.

## 1. `workers-best-practices` / migration guidance: scope edge-HTMLRewriter DOM mutation to non-hydrating sites

The edge-HTMLRewriter content-mutation pattern (e.g. CRO/experiment variants rewritten at the edge) silently fails on any hydrating framework: React client hydration reverts every edge mutation after the response lands, while the edge has already logged variant exposure. Observed on a Next.js static export: visitors saw control regardless of assigned variant, analytics logged `variant_exposure` for content never rendered — an experiment loop training on randomized data. Nothing at the network layer looks wrong; the response is correct, the client undoes it.

Suggested doc line: edge-DOM-mutation only works on non-hydrating static sites. For hydrated frameworks the edge layer's job is cookie assignment + exposure logging only; variant content must render client-side from a bundle-baked map.

## 2. Compliance guidance: address BAA availability before recommending a Workers migration

When the skills recommend migrating a Node app to Workers, there's no prompt to check whether the workload is HIPAA-adjacent. We had a migration evaluation stop late on exactly this question. It would help if the skills stated plainly whether/where a BAA is available for the edge runtime (and if it isn't, flagged that compliance-sensitive workloads should verify before migrating) — that's a hard-to-reverse architecture decision to discover post-migration.

## Bonus: `cloudflare-email-service` — never probe guessed DKIM selectors

A production domain was declared "no SPF, no DKIM, DMARC p=reject → broken" — false alarm caused by probing only guessed selector names (apex + `cf2024`). Enumerating ALL TXT records showed DKIM correctly configured at **`cf-bounce`** — which is the selector Cloudflare Email Routing actually uses for send. Suggested checklist step: list all TXT records first; never conclude absence from a guessed-selector miss. Encoding "CF send selector = `cf-bounce`, not `cf2024`" directly in the skill would prevent the trap entirely.

Contributor guide

Open the contributing guide

Research direction

Locate the workers-best-practices migration guidance and the cloudflare-email-service skill, then review their existing HTMLRewriter, compliance, and DKIM-check sections. Update the guidance to distinguish hydrating sites, require BAA verification before HIPAA-sensitive migrations, and inspect all TXT records while identifying cf-bounce as the send selector; done means all three production traps are explicitly covered.

Written by the indexing model from the issue text.

Assessment

Tech stack
next.js, react
Domain
cloud, documentation, security, web-dev
Issue type
Documentation
Difficulty
4/5
Estimated time
3-5 days
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
52/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.