cloudflare / cloudflare/skills
Edge HTMLRewriter mutation vs React hydration, BAA guidance, and the cf-bounce DKIM selector trap
- 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
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