Cloudflare Workers Integration

The Toggly Cloudflare Worker sits in front of your origin (docs site, marketing site, or any static host) and enforces feature flags at the edge. It is a deployable worker, not an npm SDK you import into your own Worker.

What it does

• Page gating: reads /toggly-page-features.json from your origin (route → flag key). If the mapped flag is off, the worker returns 404 (default) or a 302 redirect.
• Content scrubbing: streams HTML through HTMLRewriter and removes elements with data-feature="flag_key" when that flag is off. It does not hide, show, or replace arbitrary CSS selectors.
• Definitions fetch: GET {TOGGLY_API_BASE_URL}/evaluated-signed/{appKey}/{environment} (default host https://definitions.toggly.io). Accepts a bare flag map or { defs: … }. Failures soft-fail to {} so gating stays closed rather than taking the site down.
• Edge cache: caches the flag map (~30s) and the page manifest (~5 minutes).
• Usage + metrics (optional): batches check/view telemetry and POSTs JSON to {TOGGLY_METRICS_BASE_URL}api/usage/stats and …/api/metrics (default https://app.toggly.io/). Workers cannot use native gRPC. Flush runs via waitUntil and never blocks flag evaluation.

It does not currently apply per-request identity or Cloudflare CF-IPCountry targeting. Request context is empty unless you extend getRequestContext in the worker source.

Quick start

1. Clone ops-ai/Toggly.CloudflareWorker and run npm install.
2. Set environment variables in wrangler.toml, the Cloudflare dashboard, or .dev.vars. All of these are plain text — if the deploy wizard shows both Secrets and Text for the same names, fill only the Text fields.

Variable	Default	Role
TOGGLY_API_BASE_URL	https://definitions.toggly.io	Flag definitions host. Worker GETs {base}/evaluated-signed/{appKey}/{environment}.
TOGGLY_ENVIRONMENT	Production	Included in the definitions path.
TOGGLY_APP_KEY	(required)	Your Toggly app key.
ORIGIN_BASE_URL	(required)	Origin the worker proxies (for example https://my-docs.pages.dev).
TOGGLY_METRICS_BASE_URL	https://app.toggly.io/	Usage/metrics gateway, not the definitions host.
TOGGLY_USAGE_ENABLED / TOGGLY_METRICS_ENABLED	enabled when TOGGLY_APP_KEY is set	Set false to opt out.

Example .dev.vars:

TOGGLY_API_BASE_URL=https://definitions.toggly.io
TOGGLY_ENVIRONMENT=Production
TOGGLY_APP_KEY=your_app_key
ORIGIN_BASE_URL=https://my-docs.pages.dev
TOGGLY_METRICS_BASE_URL=https://app.toggly.io/

3. Run locally with npm run dev, then deploy with npm run deploy. Attach a route or custom domain (for example docs.example.com/*).

Origin contract

Your origin should serve:

• /toggly-page-features.json: map of path → feature key. Docusaurus, Gatsby, and Astro Toggly plugins emit this at build time. Paths without an entry are not page-gated.
• HTML with optional data-feature="your-flag-key" on elements that should be stripped when the flag is off.

Mark the page in frontmatter (plugin-specific) so the manifest is generated, for example x-feature: beta-feature.

Customization

In the worker repo, not via extra env vars:

• Page-level 404 vs redirect: WORKER_CONFIG in src/index.ts (redirect default path is /upgrade).
• Identity for usage hashing: extend getRequestContext in src/index.ts.
• Cache TTLs: src/flags.ts and src/manifest.ts.

Docusaurus on Cloudflare Pages

If the site is a Cloudflare Pages project, prefer the Pages Function in the Docusaurus SDK (functions/_middleware.ts). That template is a different codebase (hydration snapshot, optional Access tokens). Use this standalone worker when the origin is GitHub Pages, Netlify, Vercel, S3, or any host that is not Pages.

Next steps

• Worker source and README: Toggly.CloudflareWorker
• Docusaurus edge gating
• Gatsby and Astro page manifests
• JavaScript SDK for in-browser evaluation (separate from this worker)