Cloudflare Worker setup

Overview

The Cloudflare Worker path is an alternative to the default Proxy path. Instead of pointing DNS at RndrKit's servers, your domain stays on Cloudflare and a small Worker decides — per request, at the edge — whether to call the RndrKit render API or forward the request to your origin.

Both paths deliver the same thing to bots: fully rendered HTML. The Worker path just moves the decision from RndrKit's infrastructure to Cloudflare's, so humans never leave Cloudflare's edge.

When to choose this path

Choose the Worker path if:

  • Your domain is already managed by Cloudflare.
  • You want human traffic to stay entirely on Cloudflare's edge (no proxy hop).
  • You are comfortable deploying a Cloudflare Worker and configuring routes.

Choose the Proxy path if:

  • Your DNS is hosted somewhere other than Cloudflare.
  • You want the simplest possible setup — two DNS records and you're done.
  • You don't want to manage a Worker.

If you're unsure, start with the Proxy path. You can switch to the Worker path later.

How it works

  1. A request hits your domain and lands at your Cloudflare Worker (via a Worker route).
  2. The Worker checks the request's User-Agent. If it matches a known bot, the Worker POSTs to https://rndrkit.io/api/v1/render with your API key and receives pre-rendered HTML to return to the bot.
  3. If the request is from a human, or the path is excluded (static assets, /api/*, .well-known/*, etc.), the Worker forwards to your Origin URL as-is.
  4. If the render API errors or times out, the Worker fails open — humans and bots both fall through to your origin so your site is never down.

Bot detection runs in the Worker, not on RndrKit. That's why the Worker path is fast for humans: RndrKit is only contacted for bots.

Before you start

  • Your domain's DNS must be managed by Cloudflare (the domain is an active zone in your Cloudflare account).
  • You have a RndrKit account with the domain added — see Connect any SPA.
  • You have generated an API key in the RndrKit dashboard under Settings -> API Keys.
  • You know your Origin URL (the host where your SPA actually runs, e.g. your-app.lovable.app).

Step 1: Generate your Worker from the dashboard

Open your domain's detail page in the RndrKit dashboard. If Cloudflare is detected on your domain, you'll see the Cloudflare Worker Setup panel. It has four collapsible sections: Worker Code, Wrangler Config, Setup Instructions, and Verify.

  1. Expand Worker Code and click the copy icon. This is the full Worker source — it's identical for every customer; all per-domain config lives in environment variables.
  2. Expand Wrangler Config and copy the generated wrangler.toml. This one is customized for your domain: it includes your Worker name, your routes (yourdomain.com/*, and the root zone if you're using a subdomain), and your ORIGIN_URL pre-filled.

Keep both handy — you'll paste them in the next step.

Step 2: Deploy the Worker to Cloudflare

You have two options. Option A uses the Cloudflare dashboard only — no CLI required. Option B uses wrangler if you prefer the CLI.

Option A: Cloudflare Dashboard

  1. Go to the Cloudflare dashboard -> Workers & Pages -> Create.
  2. Click Create Worker and give it a name like rndrkit-prerender.
  3. Replace the default code with the Worker code you copied in Step 1.
  4. Click Deploy.
  5. Go to your Worker -> Settings -> Variables and Secrets.
  6. Add a secret named RNDRKIT_API_KEY — value is your RndrKit API key.
  7. Add a variable named ORIGIN_URL — value is your origin (e.g. https://your-app.lovable.app).
  8. Add a variable named RNDRKIT_API_URL — value is https://rndrkit.io/api/v1/render.

The Worker also reads two optional variables:

  • WWW_REDIRECT — set to "true" to 301-redirect apex requests to www.
  • RENDER_TIMEOUT_MS — render API timeout in ms (default 15000).

Option B: Wrangler CLI

Save the Worker code as rndrkit-worker.js and the wrangler config as wrangler.toml in the same directory, then:

npx wrangler secret put RNDRKIT_API_KEY
npx wrangler deploy

Wrangler will prompt for the API key value, then deploy the Worker and bind the routes defined in wrangler.toml.

Step 3: Map the Worker to your domain

Routes attach the Worker to specific hostnames. If you used the generated wrangler.toml, the routes are already defined and wrangler deploy set them up for you. If you deployed through the dashboard, add them manually:

  1. In your Worker, go to Settings -> Domains & Routes.
  2. Add a route with pattern yourdomain.com/* and zone set to your root domain.
  3. If you're also serving www, add a second route: www.yourdomain.com/* on the same zone. (If your RndrKit domain is already www.yourdomain.com, do the reverse — add yourdomain.com/* as the second route.)

DNS for the hostname must be proxied (orange cloud) on Cloudflare. Worker routes only fire on proxied records. If the record is gray-cloud (DNS only), Cloudflare skips the Worker and requests go straight through — meaning bots will never get pre-rendered HTML.

Point the DNS record for the hostname at anything that resolves (an A record to your origin's IP is fine) — Cloudflare's edge intercepts before the record is followed, so the Worker always runs first.

Step 4: Verify

Open the Verify section of the Cloudflare Worker Setup panel and click Verify Worker.

The dashboard checks whether your domain's Worker has called the RndrKit render API within the last 5 minutes. If it has, you'll see:

Worker verified! Bot requests are being routed through RndrKit.

If it hasn't, you'll see:

Worker not detected yet. Deploy the Worker and try again.

The verify check is passive — it only confirms that a call came in. To actively trigger one, send a bot request yourself from your terminal:

curl -A "Googlebot/2.1" https://yourdomain.com/

You should get fully rendered HTML back. The response also includes a header:

X-Prerender: true

That header is your proof the Worker called RndrKit and returned pre-rendered content. Now click Verify Worker again — it should flip to verified.

Compare against a normal request:

curl https://yourdomain.com/

This one should return your SPA shell (the origin response) with no X-Prerender header.

Troubleshooting

Verify keeps saying "Worker not detected yet." The verify endpoint checks whether your Worker has POSTed to /api/v1/render in the last 5 minutes. If a bot curl returns HTML but verify still fails, make sure the Worker actually reached the render API — check the Worker's Logs tab in Cloudflare. Missing X-Prerender: true on bot responses means the Worker isn't reaching RndrKit.

Bot requests return the SPA shell instead of pre-rendered HTML. Either the route isn't attached (requests are bypassing the Worker), or the DNS record is gray-cloud. Confirm the Worker route covers the exact hostname you're testing and that the matching DNS record has the orange cloud enabled.

Render API returns 403 DOMAIN_NOT_FOUND. The customDomain in the Worker request must match the domain on your RndrKit account exactly. The Worker sends hostname from the request URL. If your RndrKit domain is www.example.com but the request came in as example.com, you'll get this error. Add both www.example.com/* and example.com/* routes so the Worker fires on whichever the bot hits — but make sure the hostname you added to RndrKit is the one bots actually resolve.

Render API returns 401 / 403 on the API key. The RNDRKIT_API_KEY secret is wrong or missing. Re-add it in the Worker's Variables and Secrets settings. Note: secrets are write-only — you can't read them back to check, only overwrite.

Worker version mismatch. The Worker sends an X-RndrKit-Worker-Version header on every render call. The dashboard tracks the last-seen version per domain. If you see an older version reported after deploying, your new Worker hasn't received traffic yet — send a bot curl to trigger a call, then refresh.

Everything looks fine but humans see errors. The Worker is fail-open: any render API error, timeout, or unexpected response should send humans straight to origin. If humans are getting 502s, the origin itself is returning them — check your Origin URL is reachable and ORIGIN_URL doesn't have a typo or trailing path.

Next

What is RndrKit?