But after running the same project on both platforms for about a week, I started exploring Cloudflare Workers as an alternative. I noticed improvements in latency (lower TTFB) and found the free tier to be more flexible for my use case.

Deploying Next.js apps on Cloudflare used to be challenging. Earlier solutions like Cloudflare Pages had limitations with full Next.js features, and tools like next-on-pages often lagged behind the latest releases.

That changed with the introduction of @opennextjs/cloudflare. It allows you to compile a standard Next.js application into a Cloudflare Worker, supporting features like SSR, ISR, middleware, and the Image component – all without requiring major code changes.

In this guide, I’ll walk you through the exact steps I used to deploy my full-stack Next.js + Supabase application to Cloudflare Workers.

This article is the runbook I wish I had when I started.

Table of Contents

• Why Choose Cloudflare Workers Over Vercel?

• Prerequisites

• The Stack

• Step 1 — Install the Cloudflare Adapter

• Step 2 — Wire OpenNext into next dev

• Step 3— Local Environment Setup with .dev.vars

• Step 4 — Deploy Your App from Your Local Machine

• Step 5 — Push your secrets to the Worker

• Step 6 — Set Up Continuous Deployment with GitHub Actions

• Step 7 — Updating the project (the daily workflow)

• Final thoughts

Why Choose Cloudflare Workers Over Vercel?

When deploying a Next.js application, Vercel is often the default choice. It offers a smooth developer experience and tight integration with Next.js.

But Cloudflare Workers provides a compelling alternative, especially when you care about global performance and cost efficiency.

Here’s a high-level comparison (at the time of writing):

Key Takeaways

• Lower latency globally: Cloudflare runs your app across hundreds of edge locations, reducing response time for users worldwide.

• Minimal cold starts: Thanks to V8 isolates, functions start almost instantly.

• Cost efficiency: The free tier is generous enough for portfolios, blogs, and many small-to-medium apps.

Trade-offs to Consider

Cloudflare Workers use a V8 isolate runtime, not a full Node.js environment. That means:

• Some Node.js APIs like fs or child_process aren't available

• Native binaries or certain libraries may not work

That said, for most modern stacks – like Next.js + Supabase + Stripe + Resend – this limitation is rarely an issue.

In short, choose Vercel if you want the simplest, plug-and-play Next.js deployment. Choose Cloudflare Workers if you want better edge performance and more flexible scaling.

Prerequisites

Before getting started, make sure you have the following set up. Most of these take only a few minutes:

• Node.js 18+ and pnpm 9+ (you can also use npm or yarn, but this guide uses pnpm.)

• A Cloudflare account 👉 https://dash.cloudflare.com/sign-up

• A Supabase account (if your app uses a database) 👉 https://supabase.com

• A GitHub repository for your project (required later for CI/CD setup)

• A domain name (optional) – You’ll get a free *.workers.dev URL by default.

Install Wrangler (Cloudflare CLI)

We’ll use Wrangler to build and deploy the application:

pnpm add -D wrangler

The Stack

Here’s the tech stack used in this project:

• Next.js (v14.2.x): Using the App Router with Edge runtime for both public and dashboard routes

• Supabase: Handles authentication, Postgres database, and Row-Level Security (RLS)

• Tailwind CSS + UI utilities: For styling, along with lightweight animation using Framer Motion

• Cloudflare Workers: Deployment powered by @opennextjs/cloudflare and wrangler

• GitHub Actions: Used to automate CI/CD and deployments

Note: If you're using Next.js 15 or later, you can remove the
--dangerouslyUseUnsupportedNextVersion flag from the build script, as it's only required for certain Next.js 14 setups.

Step 1 — Install the Cloudflare Adapter

From inside your existing Next.js project, install the OpenNext adapter along with Wrangler (Cloudflare’s CLI tool):

pnpm add @opennextjs/cloudflare
pnpm add -D wrangler

Then add the deploy scripts to package.json:

{
  "scripts": {
    "dev": "next dev",
    "build": "next build",
    "start": "next start",
    "lint": "next lint",

    "cloudflare-build": "opennextjs-cloudflare build --dangerouslyUseUnsupportedNextVersion",
    "preview":          "pnpm cloudflare-build && opennextjs-cloudflare preview",
    "deploy":           "pnpm cloudflare-build && wrangler deploy",
    "upload":           "pnpm cloudflare-build && opennextjs-cloudflare upload",
    "cf-typegen":       "wrangler types --env-interface CloudflareEnv cloudflare-env.d.ts"
  }
}

What each script does:

Heads up: the Pages-based @cloudflare/next-on-pages is a different tool. We are not using Pages — we're deploying as a real Worker. Don't mix the two.

Step 2 — Wire OpenNext into next dev

So that pnpm dev can read your Cloudflare bindings (env vars, R2, KV, D1, …) the same way production will, edit next.config.mjs:

/** @type {import('next').NextConfig} */
const nextConfig = {};

if (process.env.NODE_ENV !== "production") {
  const { initOpenNextCloudflareForDev } = await import(
    "@opennextjs/cloudflare"
  );
  initOpenNextCloudflareForDev();
}

export default nextConfig;

We only call it in development so next build stays fast and CI doesn't spin up a Miniflare instance for nothing.

Step 3 — Local Environment Setup with .dev.vars

When working with Cloudflare Workers locally, Wrangler uses a file called .dev.vars to store environment variables (instead of .env.local used by Next.js).

A simple and reliable approach is to keep an example file in your repo and ignore the real one.

Example: .dev.vars.example (committed)

NEXT_PUBLIC_SUPABASE_URL="https://YOUR-PROJECT-ref.supabase.co"
NEXT_PUBLIC_SUPABASE_ANON_KEY="YOUR-ANON-KEY"
NEXT_PUBLIC_DASHBOARD_DEFAULT_EMAIL="admin@example.com"

Set Up Your Local Environment

Run the following commands:

cp .dev.vars.example .dev.vars
cp .dev.vars .env.local

• .dev.vars is used by Wrangler (wrangler dev)

• .env.local is used by Next.js (next dev)

Why Use Both Files?

• next dev reads from .env.local

• wrangler dev (used in pnpm preview) reads from .dev.vars

Keeping both files in sync ensures your app behaves consistently in development and when running in the Cloudflare runtime.

Update .gitignore

Make sure these files are ignored:

.dev.vars
.env*.local
.open-next
.wrangler

Step 4 — Deploy Your App from Your Local Machine

Once pnpm preview is working correctly, you're ready to deploy your application:

pnpm deploy

Under the hood that runs:

pnpm cloudflare-build && wrangler deploy

The first time, Wrangler will:

1. Compile your app to .open-next/worker.js.

2. Upload the script + assets to Cloudflare.

3. Print your live URL, e.g. https://porfolio.<your-account>.workers.dev.

Open it in a browser. Congratulations — you're on Cloudflare's edge in 330+ cities. The page should be served in <100 ms TTFB from anywhere.

Here's the live version of my own portfolio deployed this way

Step 5 — Push Your Secrets to the Worker

Local .dev.vars is not uploaded by wrangler deploy. You have to push secrets explicitly:

wrangler secret put NEXT_PUBLIC_SUPABASE_URL
wrangler secret put NEXT_PUBLIC_SUPABASE_ANON_KEY
wrangler secret put NEXT_PUBLIC_DASHBOARD_DEFAULT_EMAIL

Each command prompts you for the value and stores it encrypted on Cloudflare. Or do it visually:

Cloudflare Dashboard → Workers & Pages → your worker → Settings → Variables and Secrets → Add.

Important: NEXT_PUBLIC_* vars are inlined into the client bundle at build time, so they also need to be available when pnpm cloudflare-build runs (locally, that's your .env.local; in CI, see Step 10).

Step 6 — Set Up Continuous Deployment with GitHub Actions

Once your local deployment is working, the next step is automating deployments so every push to the main branch updates production automatically.

With this workflow:

• Pull requests will run validation checks

• Production deploys only happen after successful builds

• Broken code never reaches your live site

Create the following file inside your project:

.github/workflows/deploy.yml

name: CI / Deploy to Cloudflare Workers

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]
  workflow_dispatch:

concurrency:
  group: cloudflare-deploy-${{ github.ref }}
  cancel-in-progress: true

jobs:
  verify:
    name: Lint and Build
    runs-on: ubuntu-latest
    timeout-minutes: 10

    steps:
      - uses: actions/checkout@v4

      - uses: pnpm/action-setup@v4
        with:
          version: 10

      - uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: pnpm

      - run: pnpm install --frozen-lockfile
      - run: pnpm lint
      - run: pnpm build
        env:
          NEXT_PUBLIC_SUPABASE_URL: ${{ secrets.NEXT_PUBLIC_SUPABASE_URL }}
          NEXT_PUBLIC_SUPABASE_ANON_KEY: ${{ secrets.NEXT_PUBLIC_SUPABASE_ANON_KEY }}
          NEXT_PUBLIC_DASHBOARD_DEFAULT_EMAIL: ${{ secrets.NEXT_PUBLIC_DASHBOARD_DEFAULT_EMAIL }}

  deploy:
    name: Deploy to Cloudflare Workers
    needs: verify
    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
    runs-on: ubuntu-latest
    timeout-minutes: 15

    steps:
      - uses: actions/checkout@v4

      - uses: pnpm/action-setup@v4
        with:
          version: 10

      - uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: pnpm

      - run: pnpm install --frozen-lockfile

      - name: Build and Deploy
        run: pnpm run deploy
        env:
          CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}
          CLOUDFLARE_ACCOUNT_ID: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
          NEXT_PUBLIC_SUPABASE_URL: ${{ secrets.NEXT_PUBLIC_SUPABASE_URL }}
          NEXT_PUBLIC_SUPABASE_ANON_KEY: ${{ secrets.NEXT_PUBLIC_SUPABASE_ANON_KEY }}
          NEXT_PUBLIC_DASHBOARD_DEFAULT_EMAIL: ${{ secrets.NEXT_PUBLIC_DASHBOARD_DEFAULT_EMAIL }}

Required GitHub repo secrets

Go to GitHub repo → Settings → Secrets and variables → Actions → New repository secret and add:

That's it. Push it to main and it'll go live in about 90 seconds. PRs run lint and build only, so broken code never reaches production.

Step 7 — Updating the Project (the Daily Workflow)

After the initial setup, the loop is boringly simple — which is the whole point. Here's what I actually do day-to-day:

Code Change

git checkout -b feat/new-section
# ...edit files...
pnpm dev                # iterate locally
pnpm preview            # final smoke test on the Worker runtime
git commit -am "feat: add new section"
git push origin feat/new-section

Open a PR and the verify that the job runs. Then review, merge, and the deploy it. The job ships to Cloudflare automatically.

Updating env Vars / Secrets

# Local
nano .dev.vars

# Production
wrangler secret put NEXT_PUBLIC_SUPABASE_URL
# ...etc.

Final Thoughts

When I started this migration, I was nervous about leaving Vercel — the Next.js DX there is genuinely excellent. But the moment you push beyond a hobby site, Cloudflare's economics and edge performance are not close.

With @opennextjs/cloudflare, the developer experience has also caught up: my pnpm dev loop is identical, my pnpm preview mimics production, and git push deploys globally in ~90 seconds.

If you've been holding off because the old Cloudflare Pages + Next.js story was rough, that era is over. Try this runbook on a side project this weekend and see for yourself.

If you found this useful, the full repo is here — feel free to clone it as a starter.

Happy shipping.

— Tarikul

It doesn't learn.

You ingest 500 documents. You ask a question. The system retrieves the three most similar chunks and hands them to the LLM. Repeat for the next query.

The system knows exactly as much as it did on day one. It's a library that never builds a card catalog, never cross-references its own shelves, never notices that three of its books are saying contradictory things.

That's what I set out to fix with a knowledge reflection layer. After every ingest, the system finds semantically related documents already in the index and asks an LLM to synthesise what's new, how it connects, and what gap remains. That synthesis gets embedded, stored, and boosted in search results.

The knowledge base gets smarter as you add more documents — not just bigger.

This tutorial shows you exactly how to build it.

Table of Contents

1. What You Will Build

2. Prerequisites

3. How to Set Up the Base System

4. Why Standard RAG Has a Memory Problem

5. Step 1: Schema Update

6. Step 2: The Reflection Engine

7. Step 3: Consolidation

8. Step 4: Wire It Into Your Ingest Handler

9. Step 5: Boost Reflections in Search

10. Step 6: Filtering by doc_type

11. What Changes After You Build This

12. Deploying

13. What to Build Next

What You Will Build

In this tutorial, you'll build a post-ingest reflection pipeline that:

1. Fires automatically after every document ingest

2. Finds the most semantically related documents already in the index

3. Asks Kimi K2.5 to synthesise a three-sentence insight linking the new document to existing knowledge

4. Stores that reflection with doc_type=reflection and a 1.5× ranking boost in search results

5. Consolidates reflections into summaries every three ingests

By the end, searching your knowledge base will surface both raw document chunks and reflection artifacts the system wrote on ingest.

Prerequisites

You will need:

• A Cloudflare account — free tier works

• Node.js v18+ and Wrangler CLI installed (npm install -g wrangler)

• Basic TypeScript familiarity

No external API keys. Everything runs on Cloudflare's infrastructure.

How to Set Up the Base System

If you have already built the RAG system from my freeCodeCamp handbook, skip this section — your system is ready for the reflection layer.

If you're starting fresh, this section gets you to a working base in about 15 minutes.

Scaffold the Project

npm create cloudflare@latest rag-reflection-system
cd rag-reflection-system

Choose: Hello World example → TypeScript → No deploy yet.

Create the Vectorize Index and D1 Database

npx wrangler vectorize create rag-index --dimensions=384 --metric=cosine
npx wrangler d1 create rag-db

Configure wrangler.toml

name = "rag-reflection-system"
main = "src/index.ts"
compatibility_date = "2026-01-01"

[[vectorize]]
binding = "VECTORIZE"
index_name = "rag-index"

[[d1_databases]]
binding = "DB"
database_name = "rag-db"
database_id = "YOUR_DB_ID"

[ai]
binding = "AI"

Create the documents Table

-- migrations/001_init.sql
CREATE TABLE IF NOT EXISTS documents (
  id TEXT PRIMARY KEY,
  content TEXT NOT NULL,
  source TEXT,
  date_created TEXT DEFAULT (datetime('now'))
);

npx wrangler d1 execute rag-db --remote --file=./migrations/001_init.sql

Add the ingest and search endpoints

Replace src/index.ts with this minimal working system:

export interface Env {
  VECTORIZE: VectorizeIndex;
  DB: D1Database;
  AI: Ai;
}

export default {
  async fetch(request: Request, env: Env, ctx: ExecutionContext): Promise<Response> {
    const url = new URL(request.url);

    if (url.pathname === '/ingest' && request.method === 'POST') {
      const { id, content, source } = await request.json() as any;

      const embResult = await env.AI.run('@cf/baai/bge-small-en-v1.5', {
        text: [content.slice(0, 512)],
      }) as any;
      const vector = embResult.data[0];

      await env.VECTORIZE.upsert([{
        id,
        values: vector,
        metadata: { content: content.slice(0, 1000), source, doc_type: 'raw' },
      }]);

      await env.DB.prepare(
        'INSERT OR REPLACE INTO documents (id, content, source) VALUES (?, ?, ?)'
      ).bind(id, content, source ?? '').run();

      return Response.json({ success: true, id });
    }

    if (url.pathname === '/search' && request.method === 'POST') {
      const { query } = await request.json() as any;

      const embResult = await env.AI.run('@cf/baai/bge-small-en-v1.5', {
        text: [query],
      }) as any;
      const vector = embResult.data[0];

      const results = await env.VECTORIZE.query(vector, {
        topK: 5,
        returnMetadata: 'all',
      });

      const context = results.matches
        .map(m => m.metadata?.content as string)
        .filter(Boolean)
        .join('\n\n');

      const answer = await env.AI.run('@cf/moonshotai/kimi-k2.5', {
        messages: [
          { role: 'system', content: 'Answer using only the context provided.' },
          { role: 'user', content: `Context:\n\({context}\n\nQuestion: \){query}` },
        ],
        max_tokens: 256,
      }) as any;

      return Response.json({ answer: answer.response, sources: results.matches.map(m => m.id) });
    }

    return new Response('RAG system running', { status: 200 });
  },
};

Deploy and Verify

npx wrangler deploy

Test it:

# Ingest a document
curl -X POST https://your-worker.workers.dev/ingest \
  -H "Content-Type: application/json" \
  -d '{"id": "doc-001", "content": "Cursor pagination beats offset pagination for live-updating datasets because offset becomes unreliable when rows are inserted or deleted during pagination."}'

# Search
curl -X POST https://your-worker.workers.dev/search \
  -H "Content-Type: application/json" \
  -d '{"query": "what pagination approach should I use?"}'

If you get a grounded answer back, the base system is working. The next sections add the reflection layer on top of this foundation.

Why Standard RAG Has a Memory Problem

Standard RAG retrieval is stateless. Every query goes in cold. The system has no memory of what it found before, no synthesis of what it learned across documents, and no growing understanding of what questions remain unanswered.

Imagine you've ingested 200 documents about your product. Twelve of them touch on a pricing decision made last year. No single one has the full picture — it's distributed across quarterly reports, meeting notes, an internal Slack export, a few Notion pages.

A user asks: "Why did we change our pricing structure?"

Standard RAG retrieves the three most similar chunks. If those three chunks collectively have the answer, great. If they don't — if the real answer requires synthesising across those twelve documents — the system has no mechanism for that. It returns fragments. The LLM makes its best guess.

The reflection layer addresses this directly. When the twelfth pricing document gets ingested, the system finds the eleven related documents, synthesises what connects them, and stores that synthesis as a retrievable artifact. The answer to "why did we change our pricing structure" exists in the index before anyone asks the question.

Not smarter retrieval — smarter indexing.

Step 1: Schema Update

The reflection layer needs two new fields in your D1 documents table. Run this migration:

-- migrations/003_add_reflection_fields.sql
ALTER TABLE documents ADD COLUMN doc_type TEXT DEFAULT 'raw';
ALTER TABLE documents ADD COLUMN reflection_score REAL DEFAULT 0;
ALTER TABLE documents ADD COLUMN parent_reflection_id TEXT;

Apply it:

wrangler d1 execute mcp-knowledge-db --remote --file=./migrations/003_add_reflection_fields.sql

doc_type distinguishes raw documents (raw), single-document reflections (reflection), and consolidated multi-reflection summaries (summary). You'll use this field to filter — exposing only reflections to users who want the distilled view, or excluding them for users who want raw source chunks.

Step 2: The Reflection Engine

Create src/engines/reflection.ts. This is the core of the layer.

import { Env } from '../types/env';
import { resolveEmbeddingModel, resolveReflectionModel } from '../config/models';

const REFLECTION_BOOST = 1.5;
const CONSOLIDATION_THRESHOLD = 3; // consolidate every N new reflections

export async function reflect(
  newDocId: string,
  newDocContent: string,
  env: Env
): Promise<void> {
  // 1. Find semantically related documents already in the index
  const embModel = resolveEmbeddingModel(env.EMBEDDING_MODEL);
  const embResult = await env.AI.run(embModel.id as any, {
    text: [newDocContent.slice(0, 512)],
  });
  const queryVector = (embResult as any).data?.[0];
  if (!queryVector) return;

  const related = await env.VECTORIZE.query(queryVector, {
    topK: 5,
    filter: { doc_type: { $eq: 'raw' } },
    returnMetadata: 'all',
  });

  const relatedDocs = (related.matches ?? []).filter(
    m => m.id !== newDocId && (m.score ?? 0) > 0.65
  );

  if (relatedDocs.length === 0) return; // nothing related yet — skip

  // 2. Build synthesis prompt
  const relatedSummaries = relatedDocs
    .slice(0, 3)
    .map((m, i) => `Document \({i + 1}: \){String(m.metadata?.content ?? '').slice(0, 300)}`)
    .join('\n\n');

  const prompt = `You are synthesising knowledge across documents in a knowledge base.

New document:
${newDocContent.slice(0, 600)}

Related existing documents:
${relatedSummaries}

Write exactly three sentences:
1. What the new document adds that the existing documents don't already cover
2. How the new document connects to or extends the existing documents
3. What gap or question remains unanswered across all these documents

Be specific. Reference actual content. Do not summarise — synthesise.`;

  // 3. Call the reflection model
  const reflModel = resolveReflectionModel(env.REFLECTION_MODEL);
  const llmResp = await env.AI.run(reflModel.id as any, {
    messages: [{ role: 'user', content: prompt }],
    max_tokens: 180,
  });

  const reflectionText = (llmResp as any)?.response?.trim();
  if (!reflectionText || reflectionText.length < 40) return;

  // 4. Embed and store the reflection
  const reflEmbResult = await env.AI.run(embModel.id as any, {
    text: [reflectionText],
  });
  const reflVector = (reflEmbResult as any).data?.[0];
  if (!reflVector) return;

  const reflectionId = `refl_\({newDocId}_\){Date.now()}`;

  await env.VECTORIZE.upsert([
    {
      id: reflectionId,
      values: reflVector,
      metadata: {
        content: reflectionText,
        doc_type: 'reflection',
        parent_id: newDocId,
        reflection_score: REFLECTION_BOOST,
        source_doc_ids: relatedDocs.map(m => m.id).join(','),
        date_created: new Date().toISOString(),
      },
    },
  ]);

  await env.DB.prepare(
    `INSERT INTO documents
     (id, content, doc_type, reflection_score, parent_id, date_created)
     VALUES (?, ?, 'reflection', ?, ?, ?)`
  )
    .bind(reflectionId, reflectionText, REFLECTION_BOOST, newDocId, new Date().toISOString())
    .run();

  // 5. Check if consolidation is due
  const recentCount = await env.DB
    .prepare(`SELECT COUNT(*) as cnt FROM documents WHERE doc_type = 'reflection' AND date_created > datetime('now', '-1 hour')`)
    .first<{ cnt: number }>();

  if ((recentCount?.cnt ?? 0) >= CONSOLIDATION_THRESHOLD) {
    await consolidate(env);
  }
}

Two things worth noting here.

First, the semantic threshold (score > 0.65) matters. Too low and you're synthesising unrelated documents. Too high and you're rarely finding connections. 0.65 works well with bge-small. You can bump it to 0.72 with qwen3-0.6b (1024d) where scores cluster higher.

The prompt structure is deliberate. Three sentences, each doing a specific job: what's new, how it connects, what remains. This keeps reflections useful for retrieval. A freeform synthesis prompt produces beautiful prose that doesn't retrieve well. This structure produces retrievable artifacts.

Step 3: Consolidation

As reflections accumulate, they need their own synthesis layer — otherwise you're adding noise at a higher abstraction level.

Add this to src/engines/reflection.ts:

export async function consolidate(env: Env): Promise<void> {
  // Fetch recent reflections not yet consolidated
  const recent = await env.DB
    .prepare(
      `SELECT id, content FROM documents
       WHERE doc_type = 'reflection'
       AND id NOT IN (
         SELECT DISTINCT parent_id FROM documents
         WHERE doc_type = 'summary' AND parent_id IS NOT NULL
       )
       ORDER BY date_created DESC
       LIMIT 6`
    )
    .all<{ id: string; content: string }>();

  if (!recent.results || recent.results.length < CONSOLIDATION_THRESHOLD) return;

  const reflectionTexts = recent.results.map((r, i) => `Reflection \({i + 1}: \){r.content}`).join('\n\n');

  const prompt = `You are consolidating multiple knowledge reflections into a single compressed insight.

${reflectionTexts}

Write two to three sentences that capture the most important cross-cutting pattern or tension across these reflections. What does the knowledge base now understand that it didn't before these documents were added? What's the most important open question?

Be precise. No preamble.`;

  const reflModel = resolveReflectionModel(env.REFLECTION_MODEL);
  const llmResp = await env.AI.run(reflModel.id as any, {
    messages: [{ role: 'user', content: prompt }],
    max_tokens: 320,
  });

  const summaryText = (llmResp as any)?.response?.trim();
  if (!summaryText || summaryText.length < 40) return;

  const embModel = resolveEmbeddingModel(env.EMBEDDING_MODEL);
  const embResult = await env.AI.run(embModel.id as any, { text: [summaryText] });
  const summaryVector = (embResult as any).data?.[0];
  if (!summaryVector) return;

  const summaryId = `summary_${Date.now()}`;

  await env.VECTORIZE.upsert([
    {
      id: summaryId,
      values: summaryVector,
      metadata: {
        content: summaryText,
        doc_type: 'summary',
        reflection_score: REFLECTION_BOOST * 1.2,
        source_reflection_ids: recent.results.map(r => r.id).join(','),
        date_created: new Date().toISOString(),
      },
    },
  ]);

  await env.DB.prepare(
    `INSERT INTO documents (id, content, doc_type, reflection_score, date_created)
     VALUES (?, ?, 'summary', ?, ?)`
  )
    .bind(summaryId, summaryText, REFLECTION_BOOST * 1.2, new Date().toISOString())
    .run();
}

Summaries get a 1.2× multiplier on top of the base reflection boost. In search results, a summary synthesising twelve related documents should rank above any single document chunk on broad conceptual queries. On specific factual queries, the raw chunks will score higher. The ranking sorts itself.

Step 4: Wire It Into Your Ingest Handler

The reflection runs as a background job. It doesn't block the ingest response — that would add 2–3 seconds to every ingest call.

In your src/handlers/ingest.ts, after you've stored the document:

import { reflect } from '../engines/reflection';

// ... existing ingest logic ...

// After VECTORIZE.upsert() and DB insert succeed:
ctx.waitUntil(
  reflect(documentId, content, env).catch(err => {
    console.warn('[reflection] failed for', documentId, err.message);
  })
);

return new Response(JSON.stringify({
  success: true,
  documentId,
  chunks: chunkCount,
  // ... rest of response
}), { headers: { 'Content-Type': 'application/json' } });

ctx.waitUntil() is the Cloudflare Workers primitive for background work. The response returns immediately. The reflection runs after. The ingest API stays fast.

The .catch() is important. A failed reflection should never fail an ingest. Raw documents are the source of truth. Reflections are derived value — useful, but not critical path.

Step 5: Boost Reflections in Search

Add the reflection boost to your ranking logic in src/engines/hybrid.ts. After RRF fusion and before returning results:

// Apply reflection boost
const boosted = results.map(r => ({
  ...r,
  score: r.doc_type === 'reflection' || r.doc_type === 'summary'
    ? r.score * (r.reflection_score ?? 1.5)
    : r.score,
}));

return boosted.sort((a, b) => b.score - a.score);

This is a post-fusion boost, not a pre-fusion rerank. The reasoning: apply RRF across all results first, so reflections earn their place on raw relevance before getting boosted. A reflection that would not rank in the top 20 on raw similarity shouldn't appear just because it has a boost multiplier.

Step 6: Filtering by doc_type

Your search endpoint should accept a doc_type filter so callers can control what they see:

// In your search request handler:
const docTypeFilter = body.filters?.doc_type;

// Pass to Vectorize query:
const vectorFilter: Record<string, unknown> = {};
if (docTypeFilter) {
  vectorFilter.doc_type = docTypeFilter;
}

This gives callers three modes:

# Only reflections and summaries
POST /search
{ "query": "pricing decisions", "filters": { "doc_type": { "$in": ["reflection", "summary"] } } }

# Only source documents
POST /search
{ "query": "pricing decisions", "filters": { "doc_type": { "$eq": "raw" } } }

# Default: all types, reflections boosted
POST /search
{ "query": "pricing decisions" }

The default (no filter) is the most useful. Let the boost do its job. Restrict to raw when you need citations. Restrict to reflections when you want the synthesised view.

What Changes After You Build This

At 200 documents, the difference becomes noticeable. Queries that previously returned five fragmented chunks now surface a reflection that already synthesised those chunks. Broad conceptual queries — "what do we know about X?" — start returning genuinely useful summaries instead of just the most-similar individual paragraph.

At 2,000 documents, the reflection layer is the most valuable part of the system. The raw chunks answer specific factual questions. The reflections and summaries answer conceptual questions that could not be answered from any single document. The system has learned something no individual document contains.

One failure mode worth knowing: if your embedding model has poor semantic clustering — old bge-small at 384d with mixed-domain documents — the related-documents retrieval step will surface weak connections and produce shallow reflections. The 0.65 threshold filters most of this out, but if you're seeing reflections that seem off-topic, your embeddings are the first thing to check.

Deploying

wrangler d1 execute mcp-knowledge-db --remote --file=./migrations/003_add_reflection_fields.sql
wrangler deploy

Then ingest a few documents and watch what happens:

# Ingest document 1
curl -X POST https://your-worker.workers.dev/ingest \
  -H "Authorization: Bearer YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"id": "doc-001", "content": "Your document text here..."}'

# After a few seconds, check if a reflection was created
curl "https://your-worker.workers.dev/search" \
  -H "Authorization: Bearer YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "your topic", "filters": {"doc_type": {"$eq": "reflection"}}}'

Reflections won't appear until there are related documents to synthesise. Ingest at least three documents on similar topics before expecting to see them.

What to Build Next

The reflection layer as described here fires after every ingest. That's expensive at high ingest volume: if you're batch-importing 10,000 documents, you don't want 10,000 individual reflection calls.

For bulk ingestion, gate it: call reflect() only when a document's similarity search returns a match above 0.8, or batch-run reflection after the bulk import completes. The POST /ingest/batch endpoint in the full repo does this.

The second thing worth building: surfacing reflections in your UI with a visual distinction. A search result that's a reflection should look different from a raw chunk. In the dashboard included in the repo, reflections render with a 💡 badge and a "synthesised from N documents" note.

Full source at github.com/dannwaneri/vectorize-mcp-worker — reflection engine, consolidation, batch ingest, dashboard, OpenAPI spec.

The codebase is TypeScript, deploys with a single wrangler deploy, runs for roughly $1–5/month at 10,000 queries/day.

Standard RAG retrieves. This learns.

For a project I was recently working on, the requirement was to use WordPress as the site's backend. Content management, blog posts, and media were all handled through the WordPress admin. The frontend was open: it could be a theme, a template, or something customized through Elementor.

I could've built the same result in Elementor, but the process would've been slower and harder to maintain. Drag-and-drop works until the design gets specific, and then every small tweak costs more time than it should.

As a full stack developer, writing code turned out to be faster for me and produced cleaner output. Tools like Claude Code make the iteration cycle even tighter. So I kept the requirement – WordPress as the backend – and decided to build the frontend separately in code.

I wanted to share how I did this so that, if you're facing similar requirements, you'll know the way forward.

By the end of this tutorial, you'll have:

• A WordPress install serving content through its REST API on a subdomain

• An Astro SSR frontend rendering the content on the root domain

• A Cloudflare Pages deployment triggered on every git push

• Security hardening for a headless WordPress setup

• Draft post preview working across both systems

Prerequisites: You should be comfortable with the command line, have basic familiarity with WordPress admin, and know enough JavaScript to read and write simple functions.

To follow along, you'll need a WordPress installation, a GitHub account, and a Cloudflare account.

Table of Contents

• Why Headless WordPress?

• The Architecture

• Why Astro?

• Infrastructure Setup

  • Step 1: Move DNS to Cloudflare

  • Step 2: Create the CMS Subdomain

• WordPress Configuration

  • Tell WordPress it Lives on the Subdomain

  • Must-Use Plugin: Redirect and Preview

  • Clean Up Plugins

• The Astro Frontend

  • astro.config.mjs

  • .env

  • src/lib/wordpress.js

  • src/middleware.js

  • src/layouts/Layout.astro

  • src/pages/blog/index.astro

  • src/pages/blog/[slug].astro

  • src/pages/sitemap.xml.ts

  • src/styles/global.css

• CI/CD with Cloudflare Pages

• Final Thoughts

• Good to Know

Why Headless WordPress?

Headless WordPress separates content management from content delivery. WordPress keeps doing what it handles well: storing content and giving editors a familiar admin interface. A separate frontend handles rendering, routing, and performance.

A few situations where this split pays off:

• Your content team is trained on WordPress and moving them elsewhere would slow everyone down. Headless preserves their workflow and gives you a modern frontend.

• Your site needs a design or interaction pattern that a WordPress theme or page builder struggles to deliver. Custom dashboards, interactive tools, data-driven layouts, or integrations with non-WordPress APIs all fit here.

• You want edge delivery and modern tooling without rebuilding content management from scratch. WordPress handles content and media well. A JavaScript frontend on a CDN handles delivery well. Headless lets each side do its job.

• You need the same content across multiple surfaces. One WordPress install feeds a marketing site, a mobile app, and an internal dashboard through the same REST API.

Headless is not a fit for every site. Skip it if your site is a simple brochure, if one person does everything in the admin, or if you have no developer time to maintain a second codebase. A regular WordPress theme is the better answer there.

The Architecture

The term "headless" means you strip WordPress of its frontend responsibility. Instead of WordPress generating and serving HTML pages to visitors, it only stores and serves content through its REST API. A separate frontend framework, in this case Astro, handles what the visitor actually sees.

When a visitor loads a page, the request hits Cloudflare Pages, which runs the Astro server. Astro fetches the relevant content from WordPress via the REST API, builds the HTML, and returns it to the visitor. WordPress never touches the visitor's browser.

Content editors log into the WordPress admin at the CMS subdomain. They write, publish, and manage content as they normally would. The moment they publish, the content is live. There's no rebuild step because Astro fetches fresh data on every request.

The REST API has been built into WordPress since version 4.7. You don't need a GraphQL plugin, a paid headless CMS service, or any extra infrastructure.

Why Astro?

You could use Next.js, Nuxt, or SvelteKit here as well. But I chose Astro because its defaults fit this use case.

Astro compiles components to plain HTML and ships zero JavaScript to the browser by default. You only add client-side JavaScript where you explicitly need it.

For a CMS-driven site, most pages need none. SSR mode means every request fetches fresh data from WordPress at runtime, so content changes go live immediately without a rebuild. Cloudflare has an official adapter that handles the build output. Tailwind v4 integrates through a Vite plugin with no config file needed.

If WordPress wasn't a requirement, I would have used Next.js with Payload CMS. Payload gives you a fully typed CMS built in TypeScript that sits inside the same Next.js project, with more control over your content schema from day one. But the requirement was WordPress, and for a WordPress REST API frontend, Astro is the faster and cleaner choice.

Infrastructure Setup

Here's my setup: domain at Namecheap, WordPress on Hostinger shared hosting, and a Google Workspace email. The steps below apply to any host, whether shared hosting with cPanel or hPanel, a VPS with Apache or Nginx, or a self-managed server.

Step 1: Move DNS to Cloudflare

First, you'll need to move your domain's nameservers to Cloudflare. This gives you free DDoS protection, SSL, and the ability to attach a custom domain to Cloudflare Pages.

Before switching, verify that all DNS records transferred correctly, including your website A or CNAME records. For email, get your MX, SPF, DKIM, and DMARC values from your email provider's admin panel and add them to Cloudflare DNS first, otherwise email breaks during propagation.

Step 2: Create the CMS Subdomain

Move WordPress to cms.yourdomain.com so the root domain is free for Astro. In Cloudflare DNS, add an A record pointing cms at your server IP, or a CNAME if your host uses a CDN hostname. Then create the subdomain in your hosting panel pointing to the same WordPress directory.

One thing people miss: your server needs its own SSL certificate for the connection between Cloudflare and your origin to work. Cloudflare handles SSL at its edge, but if the origin has no certificate, you get a 525 error.

On Hostinger, this isn't automatic for new subdomains. Install it manually through hPanel. On cPanel, use Let's Encrypt. On a VPS, use Certbot.

Moving WordPress off the root domain also means /wp-admin no longer exists at your main domain, which reduces exposure. But the default login path is still /wp-admin on the subdomain. That is the first thing you should change — more on this in the Good to Know section at the end.

WordPress Configuration

Tell WordPress it Lives on the Subdomain

In wp-config.php, before the "That's all, stop editing!" comment:

define('WP_HOME',    'https://cms.yourdomain.com');
define('WP_SITEURL', 'https://cms.yourdomain.com');

WordPress admin is now at cms.yourdomain.com/wp-admin. The old path at the root domain stops working. That's intentional.

Must-Use Plugin: Redirect and Preview

WordPress has a folder called mu-plugins inside wp-content. Files placed there are treated as must-use plugins. They load automatically on every request, before regular plugins, and there is no way to activate or deactivate them through the admin UI. This makes them the right place for behaviour you never want accidentally turned off.

Create wp-content/mu-plugins/headless-redirect.php:

<?php
/*
Plugin Name: Headless Redirect
Description: Redirects frontend visitors to the Astro site and rewires the WordPress preview link.
*/

add_action('template_redirect', function() {
    if (is_user_logged_in()) return;
    if ($_SERVER['HTTP_HOST'] === 'cms.yourdomain.com') {
        wp_redirect('https://yourdomain.com', 302);
        exit;
    }
});

add_filter('preview_post_link', function(\(link, \)post) {
    $token = HEADLESS_PREVIEW_SECRET;
    \(type  = \)post->post_type;
    return 'https://yourdomain.com/preview?type=' . \(type . '&id=' . \)post->ID . '&token=' . $token;
}, 10, 2);

The template_redirect action fires when WordPress is about to render a page. If the visitor isn't logged in and the request is on the CMS subdomain, it redirects them to the main frontend. Logged-in editors pass through to the admin normally. REST API requests to /wp-json/... don't go through template_redirect at all, so they are unaffected.

The preview_post_link filter changes what happens when an editor clicks Preview on a draft post. By default, WordPress previews using its own theme, which in a headless setup renders blank.

This filter replaces that URL with a request to your Astro /preview page, passing the post ID, post type, and a secret token. Your Astro preview page uses those values to fetch the draft via the REST API and renders it exactly as it would appear live.

Clean Up Plugins

Now it's time to remove everything that renders the frontend: page builders, caching plugins, and hosting onboarding plugins.

But you'll want to keep Akismet, Wordfence, and Yoast SEO. Yoast adds SEO meta and Open Graph data directly to the REST API response, which your Astro pages read through post.yoast_head_json.

Then switch the active theme to a lightweight default. WordPress requires one active, but nobody sees it.

The Astro Frontend

Start with pnpm create astro@latest, then install the Cloudflare adapter and Tailwind:

pnpm add @astrojs/cloudflare
pnpm add -D @tailwindcss/vite tailwindcss

astro.config.mjs

import { defineConfig } from 'astro/config'
import cloudflare from '@astrojs/cloudflare'
import tailwindcss from '@tailwindcss/vite'

export default defineConfig({
  output: 'server',
  adapter: cloudflare({ imageService: 'passthrough' }),
  vite: { plugins: [tailwindcss()] },
})

output: 'server' puts Astro into full SSR mode. Without it, Astro pre-renders pages at build time, which breaks dynamic routes like /blog/[slug] that depend on WordPress content that didn't exist at build time.

imageService: 'passthrough' is required specifically for Cloudflare Workers. Astro's default image service uses Sharp, which depends on child_process and fs. Those Node.js built-ins don't exist in the Cloudflare Workers runtime. The deployment fails with a module resolution error. Setting passthrough skips image processing entirely and renders standard <img> tags instead.

.env

WORDPRESS_API_URL=https://cms.yourdomain.com

Add this same variable in Cloudflare Pages project settings under Environment Variables before deploying.

src/lib/wordpress.js

This file is the single place all WordPress API calls go through. Centralising them means if the API URL or authentication changes, you update one file.

The _embed parameter is important. By default, a post response only includes the post data. Featured images, author details, and categories are separate entities with their own IDs. Without _embed, you would need additional API requests to fetch each one. Adding it inlines all that related data into the same response.

cache: 'no-store' on every fetch call is not optional. Cloudflare Workers runs a fetch cache internally that's separate from HTTP Cache-Control headers. Without disabling it, Cloudflare caches your WordPress API responses at the edge. An editor publishes a post and sees the old version on the frontend because the cached response is being served.

const WP_URL = import.meta.env.WORDPRESS_API_URL

const fetchWP = (path) =>
  fetch(`\({WP_URL}\){path}`, { cache: 'no-store' }).then((r) => r.json())

export const getPosts = (page = 1, perPage = 10) =>
  fetchWP(`/wp-json/wp/v2/posts?_embed&per_page=\({perPage}&page=\){page}`)

export const getPostBySlug = async (slug) => {
  const posts = await fetchWP(`/wp-json/wp/v2/posts?_embed&slug=${slug}`)
  return posts[0]
}

export const getCategories = () =>
  fetchWP(`/wp-json/wp/v2/categories`)

export const getPostsByCategory = (categoryId, page = 1) =>
  fetchWP(`/wp-json/wp/v2/posts?_embed&categories=\({categoryId}&page=\){page}`)

export const getAllPostsForSitemap = () =>
  fetchWP(`/wp-json/wp/v2/posts?_fields=slug,modified&per_page=100`)

The sitemap function uses _fields instead of _embed to fetch only the fields it needs, keeping that request lightweight.

src/middleware.js

Middleware runs on every request before the page handler. This one adds Cache-Control: no-store to every SSR response so Cloudflare doesn't cache the rendered HTML pages.

export function onRequest(_context, next) {
  return next().then(response => {
    const newResponse = new Response(response.body, response)
    newResponse.headers.set('Cache-Control', 'no-store, no-cache, must-revalidate')
    newResponse.headers.set('CDN-Cache-Control', 'no-store')
    return newResponse
  })
}

The original Response from Astro has immutable headers, so you can't call .headers.set() on it directly. The fix is to construct a new Response using the original body and response as the init argument. The new Response has mutable headers, so .set() works. CDN-Cache-Control is a Cloudflare-specific header that controls caching at the edge independently from the standard Cache-Control header.

src/layouts/Layout.astro

Every page goes through this layout. HTML structure, meta tags, and global imports live here so you don't repeat them on every page.

---
interface Props {
  title: string
  description?: string
}
const { title, description = '' } = Astro.props
---
<!doctype html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>{title}</title>
    <meta name="description" content={description} />
  </head>
  <body>
    <slot name="nav" />
    <main id="main-content"><slot /></main>
    <slot name="footer" />
  </body>
</html>

Named slots let the navbar and footer sit outside <main>, keeping the HTML landmark structure correct for accessibility.

src/pages/blog/index.astro

---
import Layout from '../../layouts/Layout.astro'
import { getPosts, getCategories, getPostsByCategory } from '../../lib/wordpress'

const page = Number(Astro.url.searchParams.get('page') ?? 1)
const categoryId = Astro.url.searchParams.get('category')

const [posts, categories] = await Promise.all([
  categoryId ? getPostsByCategory(categoryId, page) : getPosts(page, 10),
  getCategories(),
])
---
<Layout title="Blog">
  <nav>
    <a href="/blog">All</a>
    {categories.map((cat) => (
      <a href={`/blog?category=${cat.id}`}>{cat.name}</a>
    ))}
  </nav>

  <ul>
    {posts.map((post) => {
      const image   = post._embedded?.['wp:featuredmedia']?.[0]?.source_url
      const imageAlt = post._embedded?.['wp:featuredmedia']?.[0]?.alt_text ?? ''
      return (
        <li>
          {image && <img src={image} alt={imageAlt} />}
          <a href={`/blog/${post.slug}`} set:html={post.title.rendered} />
          <div set:html={post.excerpt.rendered} />
        </li>
      )
    })}
  </ul>

  {page > 1 && <a href={`/blog?page=${page - 1}`}>Previous</a>}
  <a href={`/blog?page=${page + 1}`}>Next</a>
</Layout>

Promise.all fetches posts and categories in parallel. The category filter reads from the URL query string so the same page handles both /blog and /blog?category=5 without separate routes.

Featured images live inside post._embedded['wp:featuredmedia'][0] because _embed inlines the media object into the post response.

src/pages/blog/[slug].astro

---
import Layout from '../../layouts/Layout.astro'
import { getPostBySlug } from '../../lib/wordpress'

const { slug } = Astro.params
const post = await getPostBySlug(slug)
if (!post) return Astro.redirect('/404')

const image    = post._embedded?.['wp:featuredmedia']?.[0]?.source_url
const imageAlt = post._embedded?.['wp:featuredmedia']?.[0]?.alt_text ?? ''
const author   = post._embedded?.author?.[0]?.name
const seoTitle = post.yoast_head_json?.title ?? post.title.rendered
const seoDesc  = post.yoast_head_json?.og_description ?? ''
---
<Layout title={seoTitle} description={seoDesc}>
  <article>
    <h1 set:html={post.title.rendered} />
    <p>{author} · {new Date(post.date).toLocaleDateString()}</p>
    {image && <img src={image} alt={imageAlt} />}
    <div set:html={post.content.rendered} />
  </article>
</Layout>

Use set:html for WordPress content, not {post.content.rendered}. Astro treats curly brace expressions as text and escapes the HTML, so you see raw tags printed on the page instead of rendered content.

Always guard with if (!post) return Astro.redirect('/404'). If someone visits a slug that doesn't exist, the API returns an empty array. Without the guard, accessing properties on undefined throws an error that crashes the Cloudflare Worker and returns a 500.

post.yoast_head_json is available when Yoast SEO is active. It contains the computed SEO title and description that Yoast generates. Using it means the SEO work done in WordPress carries over to the Astro frontend automatically.

src/pages/sitemap.xml.ts

import type { APIRoute } from 'astro'
import { getAllPostsForSitemap } from '../lib/wordpress'

export const GET: APIRoute = async () => {
  const posts = await getAllPostsForSitemap()

  const urls = [
    { loc: 'https://yourdomain.com/', lastmod: new Date().toISOString() },
    { loc: 'https://yourdomain.com/blog/', lastmod: new Date().toISOString() },
    ...posts.map((p) => ({
      loc: `https://yourdomain.com/blog/${p.slug}/`,
      lastmod: p.modified,
    })),
  ]

  const xml = `<?xml version="1.0" encoding="UTF-8"?>
<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
\({urls.map((u) => `  <url>\n    <loc>\){u.loc}</loc>\n    <lastmod>${u.lastmod}</lastmod>\n  </url>`).join('\n')}
</urlset>`

  return new Response(xml, { headers: { 'Content-Type': 'application/xml' } })
}

This generates fresh XML on every request, so the sitemap always reflects currently published posts without a rebuild.

src/styles/global.css

@import "tailwindcss";

@theme {
  --color-brand: #your-color;
  --font-sans: 'Your Font', sans-serif;
}

Tailwind v4 uses CSS-first configuration through the @theme block. CSS variables defined here become Tailwind utilities automatically. --color-brand becomes bg-brand, text-brand, and so on. No tailwind.config.js needed.

CI/CD with Cloudflare Pages

With the Astro code in place, the last piece is getting it deployed. Cloudflare Pages connects directly to GitHub, so you don't have to maintain a separate pipeline.

Here are the steps:

1. Push your repo to GitHub.

2. Go to Cloudflare Pages, create a project, connect it to your GitHub repository.

3. Set the build command to pnpm build and the output directory to dist.

4. Under Environment Variables, add WORDPRESS_API_URL pointing to https://cms.yourdomain.com.

5. Deploy.

After the first deploy, every push to main triggers a new deployment automatically. Cloudflare runs the build, and within minutes the new version is live globally. Content updates in WordPress go live immediately, since Astro fetches from WordPress on every request. A developer pushing code and an editor publishing a post are completely independent operations.

Final Thoughts

This setup exists because of the specific requirement that the content team was already on WordPress and changing that was not on the table.

If you're starting fresh with no CMS in place, this is probably not the stack you want. Go with something like Next.js and Payload CMS where the backend and frontend are designed to work together from the start.

But if your situation matches where content editors are already familiar with WordPress, and you need a custom frontend that a page builder can't deliver cleanly, then this separation makes sense.

Pros:

• Content editors keep using WordPress. No retraining, no migration.

• The frontend has full control over design and behaviour. No theme or plugin constraints.

• Deployments are automatic on every push. Content changes go live immediately without a rebuild.

• No added cost for most sites. WordPress stays on its existing host. Cloudflare Pages is free within generous limits, and scales to $5 per month on the Workers Paid plan if you outgrow them.

Cons:

• Two systems to maintain instead of one. You operate the WordPress install (updates, plugins, backups) and maintain the Astro codebase separately.

• The WordPress REST API has limitations. Complex content structures or real-time features need more work to handle compared to a purpose-built headless CMS.

• Adapter and deployment target are tied together. @astrojs/cloudflare v13 drops Pages support in favor of Workers, so staying on Pages means staying on v12. Details in the Good to Know section.

• Frontend changes require a developer. With Elementor, anyone with admin access could adjust layouts directly in the browser. Here, any visual change outside of content goes through code, which means it goes through you.

The stack is WordPress on existing hosting, Astro on Cloudflare Pages, with GitHub as the bridge between development and production. It solves a specific problem cleanly. Outside of that problem, there are better options.

Good to Know

Change the default login URL immediately. Every bot targets /wp-login.php and /wp-admin. Install WPS Hide Login and move it to something custom. Anyone hitting the default paths gets a 404.

Remove the /wp-json/wp/v2/users endpoint. It returns a public list of usernames. In headless mode you get author data through _embed and have no use for this endpoint. Add to the mu-plugin:

add_filter('rest_endpoints', function($endpoints) {
    unset($endpoints['/wp/v2/users']);
    unset($endpoints['/wp/v2/users/(?P<id>[\d]+)']);
    return $endpoints;
});

Disable XML-RPC and enable 2FA. Add add_filter('xmlrpc_enabled', '__return_false') to the mu-plugin — you aren't using it in headless mode and it's a common brute force target. Enable Wordfence's Brute Force Protection and add two-factor authentication through WP 2FA for all admin accounts.

Don't upgrade @astrojs/cloudflare to v13 if you deploy via Cloudflare Pages git-push CI. v12 outputs dist/_worker.js which Pages CI expects. v13 outputs a different format for wrangler deploy — Pages CI falls back to serving the dist folder as a static site and every SSR route returns 404 with no helpful error message.

The v12 adapter throws a deprecation warning on entrypointResolution. Silence it by adding entrypointResolution: 'auto' to the adapter options. Test before committing — it changes how the build locates the Worker entry file.

Custom Post Types follow the same pattern. Register the CPT with show_in_rest: true and a rest_base, and it shows up at /wp-json/wp/v2/your-base. The same fetch helpers, _embed, and slug routing work exactly the same way.

The REST API returns pagination headers. The raw response includes X-WP-Total and X-WP-TotalPages headers before you call .json(). If you want proper previous/next pagination, read those instead of guessing whether a next page exists.

Wrap API calls in try/catch. If WordPress is unreachable, an unhandled fetch throws and returns a 500. A try/catch returns an empty page instead, which is a much better failure mode.

Preview auth uses Application Passwords. WordPress 5.6 added Application Passwords under Users → Profile. That's what WP_APP_USER and WP_APP_PASSWORD in your .env should point to — not your regular admin password. Generate one per environment. Define the preview token as a constant in wp-config.php (define('HEADLESS_PREVIEW_SECRET', '...')) and reference that constant in the mu-plugin — never hardcode secrets in version-controlled files.

This tutorial is different. I run a production RAG system (vectorize-mcp-worker) that handles real traffic at a total cost of \(5/month. The alternatives I evaluated ranged from \)100–$200/month. The difference isn't magic. It's architecture.

Here, you'll build rag-tutorial-simple: a clean, minimal RAG chatbot deployed on Cloudflare Workers. No external API keys. No paid vector database subscriptions. No servers to manage. Just Cloudflare's free tier – Workers, Vectorize, and Workers AI – doing the heavy lifting at the edge.

Table of Contents

1. What You Will Build

2. Prerequisites

3. How RAG Works

4. How to Set Up Your Project

5. How to Build the Data Pipeline

6. How to Build the Query Pipeline

7. How to Add Error Handling and Security

8. Performance and Cost Analysis

9. Conclusion

What You Will Build

By the end of this tutorial, you'll have a globally deployed RAG API that:

• Accepts a natural language question via HTTP

• Converts it to a vector embedding using Workers AI

• Searches a knowledge base stored in Cloudflare Vectorize

• Passes the retrieved context to an LLM (also on Workers AI) to generate an answer

• Returns a grounded, accurate response (not a hallucination)

The complete source code is available at github.com/dannwaneri/rag-tutorial-simple.

Prerequisites

This is an intermediate-level tutorial. You should be comfortable with:

• JavaScript/TypeScript: async/await, promises, basic types

• HTTP APIs: REST, request/response, JSON

• Command line basics: running npm commands, navigating directories

You will need:

• Node.js 18 or higher: check with node --version

• A Cloudflare account: free tier is fine, sign up at cloudflare.com

• A code editor: VS Code recommended for TypeScript support

That's it. No OpenAI key. No credit card for embeddings. Let's build.

How RAG Works

Before you write any code, you'll need a clear mental model of what you're building. This section explains the three core components of a RAG system, how data flows between them, and why this architecture works at scale.

The Mental Model

Think of a traditional LLM like a doctor who studied medicine for years but has been in a remote cabin with no internet since their graduation day. They are brilliant, but they only know what they knew when they left. Ask them about a drug approved last year and they'll either say they don't know or – worse – confidently give you wrong information.

RAG gives that doctor access to an up-to-date medical library. Before answering your question, they can look up the relevant pages, read them, and use that information to give you an accurate answer. Their training still matters (that is, they know how to read and interpret the information), but they're no longer limited to what they memorized years ago.

In technical terms, RAG works in three steps on every request:

1. Retrieve: find the most relevant documents from your knowledge base

2. Augment: add those documents to the LLM prompt as context

3. Generate: let the LLM produce an answer using both its training and the retrieved context

The Three Components

Every RAG system has three moving parts. Understanding each one will help you debug problems and make better architectural decisions as you build.

The Embedding Model

An embedding model converts text into a vector – an array of numbers that represents the meaning of that text. The model you will use in this tutorial, @cf/baai/bge-base-en-v1.5, outputs 768 numbers for any piece of text you give it.

The critical property of embeddings is that semantically similar text produces numerically similar vectors. "How do I install Node.js?" and "What's the process for setting up Node?" will produce vectors that are close together. "How do I install Node.js?" and "What is the capital of France?" will produce vectors that are far apart.

This is what makes semantic search possible. You aren't matching keywords, you're matching meaning.

One rule you must never break: your documents and your queries must be embedded with the same model. If you embed your documents with bge-base-en-v1.5 and your queries with a different model, the vectors won't be comparable and your searches will return garbage.

The Vector Database

The vector database stores your embeddings and lets you search them by similarity. In this tutorial, you'll use Cloudflare Vectorize.

When you run a similarity search, you pass in a query vector and Vectorize returns the K most similar vectors it has stored, along with their metadata and similarity scores. This is called approximate nearest neighbor search, and Vectorize is optimized to do it fast even across millions of vectors.

The key advantage of using Vectorize over an external vector database like Pinecone is co-location. Vectorize runs in the same Cloudflare network as your Worker. There's no external API call, no authentication roundtrip, and no network latency between your application and your database.

The Language Model

The LLM is responsible for one thing: reading the retrieved context and generating a natural language answer. It doesn't search anything. It doesn't decide what's relevant. It just reads what you give it and writes a response.

This separation of concerns is intentional. The LLM is good at language: understanding questions, synthesizing information, writing clearly. The vector database is good at retrieval: finding relevant documents fast. RAG combines their strengths without asking either component to do something it is not designed for.

In this tutorial you'll use @cf/meta/llama-3.3-70b-instruct-fp8-fast through Workers AI. No API key required.

A Note on Visual Embeddings

If you plan to extend this system to search images, you may be tempted to use a vision-language model like CLIP to generate visual embeddings (vectors that represent the image itself rather than a text description of it). This sounds clever but works worse for RAG in practice.

Visual embeddings match pixel similarity. They are good for "find images that look like this one." They are poor for "find the login screen" or "find dashboards showing error rates" because those queries are about meaning, not pixels.

The better approach – used in production – is to pass the image through a multimodal model like Llama 4 Scout, which generates a detailed text description and extracts visible text via OCR. You then embed that description using the same BGE model as your other documents.

The result lives in one unified index, works with your existing query pipeline, and produces better search results than visual embeddings for RAG use cases.

Cloudflare Workers AI does not support CLIP anyway. But even if it did, descriptions would outperform it for semantic search.

How a Query Flows Through the System

Here is exactly what happens when a user sends the question "What is RAG?" to your finished Worker:

1. Step 1 – Embed the question (20-30ms): Your Worker calls Workers AI with the question text. The embedding model returns a 768-dimensional vector representing the meaning of the question.

2. Step 2 – Search Vectorize (30-50ms): Your Worker passes that vector to Vectorize, which searches your knowledge base and returns the 3 most similar documents with their similarity scores.

3. Step 3 – Filter and build context (< 1ms): Documents with a similarity score below 0.5 are discarded. The remaining document texts are joined into a context string.

4. Step 4 – Generate the answer (500-1500ms): Your Worker sends the context and the question to the LLM. The LLM reads the context and generates a grounded answer.

5. Step 5 – Return to the user: The answer and source metadata are returned as JSON.

Total time: typically 600-1600ms end to end. The LLM generation step dominates. Everything else is fast.

Why This Works at Scale

A common objection to Cloudflare RAG is that it cannot meet sub-200ms retrieval requirements. That objection comes from a specific architectural mistake: trying to run the entire RAG pipeline, including heavy embedding generation and reranking, inside a single synchronous request. That's the wrong architecture.

The architecture you're building in this tutorial separates the loading step (which is slow and runs once) from the query step (which is fast and runs on every request). By the time a user asks a question, your documents are already embedded and stored. The query pipeline only needs to embed the question, run one vector search, and call the LLM. Those three steps are fast.

My production system (vectorize-mcp-worker) runs this architecture and handles real traffic at $5/month. The full performance breakdown is here. Cloudflare RAG works. You just have to build it correctly.

How to Set Up Your Project

In this section, you'll scaffold a Cloudflare Worker, create a Vectorize index to store your embeddings, and configure the bindings that connect them together.

How to Create the Project

Open your terminal and create a new directory for the project.

On Mac/Linux:

mkdir rag-tutorial-simple && cd rag-tutorial-simple

On Windows PowerShell:

mkdir rag-tutorial-simple
cd rag-tutorial-simple

Then run the Cloudflare scaffolding tool:

npm create cloudflare@latest

Answer the prompts like this:

• Directory/app name: rag-tutorial-simple

• What would you like to start with? Hello World example

• TypeScript? Yes

• Deploy? No

When it finishes, you'll have a working TypeScript Worker with Wrangler already configured.

How to Create the Vectorize Index

Vectorize is Cloudflare's vector database. It lives in the same network as your Worker, which means no external API call and no added latency when you search it.

npx wrangler vectorize create rag-tutorial-index --dimensions=768 --metric=cosine

Two things to note here.

--dimensions=768 tells Vectorize how many numbers make up each embedding. This must match the output of the embedding model you use. The model you will use (@cf/baai/bge-base-en-v1.5) outputs 768 dimensions. If this number doesn't match, your searches will fail.

--metric=cosine is how Vectorize measures similarity between vectors. Cosine similarity measures the angle between two vectors rather than the distance between them. For text embeddings, this captures semantic meaning more accurately than other metrics.

How to Configure wrangler.toml

Open wrangler.toml and replace its contents with the following:

name = "rag-tutorial-simple"
main = "src/index.ts"
compatibility_date = "2026-02-25"

[[vectorize]]
binding = "VECTORIZE"
index_name = "rag-tutorial-index"

[ai]
binding = "AI"

The [[vectorize]] block connects your Worker to the index you just created. The [ai] block gives your Worker access to Workers AI – both for generating embeddings and for running the language model that produces answers.

Notice that there are no API keys anywhere. Cloudflare handles authentication internally because everything – your Worker, Vectorize, and Workers AI – runs under the same account.

How to Update src/index.ts

Open src/index.ts and replace the generated code with this:

export interface Env {
  VECTORIZE: VectorizeIndex;
  AI: Ai;
  LOAD_SECRET: string;
}

export default {
  async fetch(request: Request, env: Env): Promise<Response> {
    return new Response("RAG tutorial worker is running", { status: 200 });
  },
};

The Env interface tells TypeScript what bindings are available inside your Worker. VectorizeIndex and Ai are types provided by Cloudflare's type definitions.

How to Verify Your Setup

Start the local development server:

npx wrangler dev

Open your browser and visit http://localhost:8787. You should see:

RAG tutorial worker is running

You will see two warnings in your terminal. Both are expected.

The first warning says that Vectorize doesn't support local mode. This means Vectorize queries won't work during local development unless you run with the --remote flag. You'll do this later when testing the full pipeline.

The second warning says the AI binding always accesses remote resources. This means that embedding generation and LLM calls always hit Cloudflare's servers, even in local development. This is fine: usage within the free tier limits costs nothing.

Your project structure at this point:

rag-tutorial-simple/
├── scripts/
│   └── knowledge-base.ts
├── src/
│   └── index.ts
├── wrangler.toml
├── package.json
└── tsconfig.json

How to Build the Data Pipeline

The data pipeline is responsible for two things: generating embeddings for each document in your knowledge base, and storing those embeddings in Vectorize. You'll handle both steps inside the Worker itself using a /load endpoint.

This approach has a key advantage: you don't need an API token, an Account ID, or any external tooling. Everything uses the bindings you already configured in wrangler.toml.

How to Create the Knowledge Base

Create a scripts/ folder in your project and add a file called knowledge-base.ts:

mkdir scripts

Add your documents to scripts/knowledge-base.ts:

export const documents = [
  {
    id: "1",
    text: "Cloudflare Workers run JavaScript at the edge, in over 300 data centers worldwide. Requests are handled close to the user, reducing latency significantly compared to a single-region server.",
    metadata: { source: "cloudflare-docs", category: "workers" },
  },
  {
    id: "2",
    text: "Vectorize is Cloudflare's vector database. It stores embeddings and lets you search them by semantic similarity. It runs in the same network as your Worker, so there is no external API call needed.",
    metadata: { source: "cloudflare-docs", category: "vectorize" },
  },
  {
    id: "3",
    text: "Workers AI lets you run machine learning models directly on Cloudflare's infrastructure. You can generate embeddings and run LLM inference without leaving the Cloudflare network.",
    metadata: { source: "cloudflare-docs", category: "workers-ai" },
  },
  {
    id: "4",
    text: "RAG stands for Retrieval Augmented Generation. Instead of relying only on what the LLM was trained on, RAG retrieves relevant context from a knowledge base and adds it to the prompt before generating an answer.",
    metadata: { source: "ai-concepts", category: "rag" },
  },
  {
    id: "5",
    text: "An embedding is a numerical representation of text. Similar pieces of text produce similar embeddings. This is what makes semantic search possible — you search by meaning, not exact keywords.",
    metadata: { source: "ai-concepts", category: "embeddings" },
  },
  {
    id: "6",
    text: "The BGE model (bge-base-en-v1.5) is available through Workers AI. It generates 768-dimensional embeddings and works well for English semantic search tasks.",
    metadata: { source: "cloudflare-docs", category: "workers-ai" },
  },
  {
    id: "7",
    text: "Cosine similarity measures the angle between two vectors. For text embeddings, it captures semantic similarity regardless of text length, which makes it more reliable than Euclidean distance.",
    metadata: { source: "ai-concepts", category: "embeddings" },
  },
  {
    id: "8",
    text: "Cloudflare Workers have a free tier that includes 100,000 requests per day. Vectorize is available on both the Workers Free and Paid plans. The free tier lets you prototype and experiment. The Workers Paid plan starts at $5/month and includes higher usage allocations for production workloads.",
    metadata: { source: "cloudflare-docs", category: "pricing" },
  },
];

Each document has three fields. The id is a unique string that Vectorize uses to identify the vector. The text is what gets converted into an embedding. The metadata is stored alongside the vector and returned in search results. You'll use it later to display the source of each answer.

Understanding Embeddings

Before writing the loading code, it helps to understand what you're actually generating.

An embedding is an array of 768 numbers that represents the meaning of a piece of text. The model reads a sentence and outputs those 768 numbers in a way where similar sentences produce similar arrays of numbers.

When a user asks a question, you convert that question into an embedding using the same model, then ask Vectorize to find the stored embeddings that are closest to it. The documents those embeddings came from are your most relevant context.

This is why the model choice matters: your documents and your queries must be embedded with the same model, or the similarity scores will be meaningless.

How to Build the Load Endpoint

Open src/index.ts and update it with a /load route. Here is the complete file at this stage:

import { documents } from "../scripts/knowledge-base";

export interface Env {
  VECTORIZE: VectorizeIndex;
  AI: Ai;
  LOAD_SECRET: string;
}

export default {
  async fetch(request: Request, env: Env): Promise<Response> {
    const url = new URL(request.url);

    if (url.pathname === "/load" && request.method === "POST") {
      return handleLoad(env, request);
    }

    return new Response("RAG tutorial worker is running", { status: 200 });
  },
};

async function handleLoad(env: Env, request: Request): Promise<Response> {
  const authHeader = request.headers.get("X-Load-Secret");
  if (authHeader !== env.LOAD_SECRET) {
    return Response.json({ error: "Unauthorized" }, { status: 401 });
  }

  const results: { id: string; status: string }[] = [];

  for (const doc of documents) {
    const response = await env.AI.run("@cf/baai/bge-base-en-v1.5", {
      text: [doc.text],
    }) as { data: number[][] };

    await env.VECTORIZE.upsert([
      {
        id: doc.id,
        values: response.data[0],
        metadata: {
          ...doc.metadata,
          text: doc.text,
        },
      },
    ]);

    results.push({ id: doc.id, status: "loaded" });
  }

  return Response.json({ success: true, loaded: results });
}

Notice that env.AI.run() and env.VECTORIZE.upsert() require no credentials. The bindings handle authentication because the Worker runs inside your Cloudflare account. There are no secrets to manage for internal service communication.

The text: doc.text field inside metadata is important. Vectorize stores the vector values and whatever metadata you provide, but it doesn't store the original text separately. By including the text in metadata, you can retrieve and display it in search results later.

The as { data: number[][] } cast is necessary because the TypeScript type definitions for Workers AI do not yet reflect the exact return shape of every model. The actual response always contains a data array, and the cast tells TypeScript to trust that.

How to Deploy and Load Your Knowledge Base

First, set the secret that will protect your load endpoint:

npx wrangler secret put LOAD_SECRET

Type a strong value when prompted. Then deploy:

npx wrangler deploy

Trigger the load endpoint. You only need to do this once, or any time you update your knowledge base:

curl -X POST https://rag-tutorial-simple.<your-subdomain>.workers.dev/load \
  -H "X-Load-Secret: your-secret-value"

On Windows PowerShell:

Note: PowerShell uses backtick (`) for line continuation, not backslash.

Invoke-WebRequest `
  -Uri "https://rag-tutorial-simple.<your-subdomain>.workers.dev/load" `
  -Method POST `
  -Headers @{"X-Load-Secret"="your-secret-value"} `
  -UseBasicParsing

You should see:

{
  "success": true,
  "loaded": [
    { "id": "1", "status": "loaded" },
    { "id": "2", "status": "loaded" },
    { "id": "3", "status": "loaded" },
    { "id": "4", "status": "loaded" },
    { "id": "5", "status": "loaded" },
    { "id": "6", "status": "loaded" },
    { "id": "7", "status": "loaded" },
    { "id": "8", "status": "loaded" }
  ]
}

Your knowledge base is now stored in Vectorize as vectors. In the next section, you'll build the query pipeline that searches those vectors and generates answers.

How to Build the Query Pipeline

The query pipeline is the core of your RAG system. When a user sends a question, the pipeline runs four steps in sequence: embed the question, search Vectorize, build context from the results, and generate an answer with the LLM.

Add a /query route to your fetch handler and the complete handleQuery function. Here is the full updated src/index.ts:

import { documents } from "../scripts/knowledge-base";

export interface Env {
  VECTORIZE: VectorizeIndex;
  AI: Ai;
  LOAD_SECRET: string;
}

export default {
  async fetch(request: Request, env: Env): Promise<Response> {
    const url = new URL(request.url);

    if (url.pathname === "/load" && request.method === "POST") {
      return handleLoad(env, request);
    }

    if (url.pathname === "/query" && request.method === "POST") {
      return handleQuery(request, env);
    }

    return new Response("RAG tutorial worker is running", { status: 200 });
  },
};

async function handleLoad(env: Env, request: Request): Promise<Response> {
  const authHeader = request.headers.get("X-Load-Secret");
  if (authHeader !== env.LOAD_SECRET) {
    return Response.json({ error: "Unauthorized" }, { status: 401 });
  }

  const results: { id: string; status: string }[] = [];

  for (const doc of documents) {
    const response = await env.AI.run("@cf/baai/bge-base-en-v1.5", {
      text: [doc.text],
    }) as { data: number[][] };

    await env.VECTORIZE.upsert([
      {
        id: doc.id,
        values: response.data[0],
        metadata: {
          ...doc.metadata,
          text: doc.text,
        },
      },
    ]);

    results.push({ id: doc.id, status: "loaded" });
  }

  return Response.json({ success: true, loaded: results });
}

async function handleQuery(request: Request, env: Env): Promise<Response> {
  const body = await request.json() as { question: string };

  if (!body.question) {
    return Response.json({ error: "question is required" }, { status: 400 });
  }

  // Step 1: Embed the question using the same model as your documents
  const embeddingResponse = await env.AI.run("@cf/baai/bge-base-en-v1.5", {
    text: [body.question],
  }) as { data: number[][] };

  // Step 2: Search Vectorize for the 3 most similar documents
  const searchResults = await env.VECTORIZE.query(
    embeddingResponse.data[0],
    {
      topK: 3,
      returnMetadata: "all",
    }
  );

  // Step 3: Build context from results above the similarity threshold
  const context = searchResults.matches
    .filter((match) => match.score > 0.5)
    .map((match) => match.metadata?.text as string)
    .filter(Boolean)
    .join("\n\n");

  if (!context) {
    return Response.json({
      answer: "I could not find relevant information to answer that question.",
      sources: [],
    });
  }

  // Step 4: Generate an answer using the retrieved context
  const aiResponse = await env.AI.run("@cf/meta/llama-3.3-70b-instruct-fp8-fast", {
    messages: [
      {
        role: "system",
        content: "You are a helpful assistant. Answer the question using only the context provided. If the context does not contain enough information, say so.",
      },
      {
        role: "user",
        content: `Context:\n\({context}\n\nQuestion: \){body.question}`,
      },
    ],
    max_tokens: 256,
  }) as { response: string };

  // Step 5: Return the answer with its sources
  const sources = searchResults.matches
    .filter((match) => match.score > 0.5)
    .map((match) => match.metadata?.source as string)
    .filter(Boolean);

  return Response.json({
    answer: aiResponse.response,
    sources: [...new Set(sources)],
  });
}

What each step does:

1. Step 1 – Embed the question: You convert the user's question into a 768-dimensional vector using the same model you used when loading your documents. This is critical: the question and the documents must be embedded with the same model or the similarity scores will be meaningless.

2. Step 2 – Search Vectorize: You pass the question embedding to Vectorize, which returns the three most similar documents. returnMetadata: "all" tells Vectorize to include the metadata you stored alongside each vector — including the original text.

3. Step 3 – Build context: You filter out any results with a similarity score below 0.5 and join the remaining document texts into a single context string. The 0.5 threshold prevents the LLM from receiving irrelevant documents just because nothing better matched.

4. Step 4 – Generate the answer: You pass the context and the question to the LLM using the chat format with messages. The system prompt explicitly instructs the model to answer using only the provided context. This is what keeps the LLM grounded. Without this instruction, it will ignore your context and answer from its training data instead.

5. Step 5 – Return sources: You include the source metadata in the response so callers know which documents the answer came from. The Set deduplicates sources in case multiple chunks came from the same document.

How to Test the Query Pipeline

Deploy your Worker:

npx wrangler deploy

Send a question:

curl -X POST https://rag-tutorial-simple.<your-subdomain>.workers.dev/query \
  -H "Content-Type: application/json" \
  -d '{"question": "What is RAG?"}'

On Windows PowerShell:

Invoke-WebRequest `
  -Uri "https://rag-tutorial-simple.<your-subdomain>.workers.dev/query" `
  -Method POST `
  -ContentType "application/json" `
  -Body '{"question": "What is RAG?"}' `
  -UseBasicParsing

You should receive a response like this:

{
  "answer": "RAG stands for Retrieval Augmented Generation. It's a method that enhances generation by retrieving relevant context from a knowledge base and adding it to the prompt before generating an answer.",
  "sources": ["ai-concepts"]
}

The answer came from your knowledge base, not from the LLM's training data. That's the entire point of RAG: grounded, verifiable answers with traceable sources.

How to Add Error Handling and Security

A tutorial that only shows the happy path is not production-ready. In this section, you'll add error handling to every step of the query pipeline and protect the /load endpoint from unauthorized access.

How to Secure the Load Endpoint

The /load endpoint generates embeddings and writes to your Vectorize index. Without protection, anyone who discovers your Worker URL can trigger it repeatedly, consuming your Workers AI quota and overwriting your data.

The LOAD_SECRET binding you added to Env and the wrangler secret put command you ran earlier handle this. The check at the top of handleLoad rejects any request that doesn't include the correct secret header:

const authHeader = request.headers.get("X-Load-Secret");
if (authHeader !== env.LOAD_SECRET) {
  return Response.json({ error: "Unauthorized" }, { status: 401 });
}

A request without the header returns {"error":"Unauthorized"} with a 401 status. The secret itself is stored as an encrypted environment variable in your Worker. It never appears in your code or wrangler.toml.

To trigger the load endpoint, you must include the secret in the request header:

curl -X POST https://rag-tutorial-simple.<your-subdomain>.workers.dev/load \
  -H "X-Load-Secret: your-secret-value"

How to Handle Query Errors

Replace your handleQuery function with this hardened version:

async function handleQuery(request: Request, env: Env): Promise<Response> {
  // Guard against malformed request body
  let body: { question: string };
  try {
    body = await request.json() as { question: string };
  } catch {
    return Response.json({ error: "Invalid JSON in request body" }, { status: 400 });
  }

  if (!body.question || typeof body.question !== "string" || body.question.trim() === "") {
    return Response.json({ error: "question must be a non-empty string" }, { status: 400 });
  }

  // Sanitize: trim whitespace and cap length
  const question = body.question.trim().slice(0, 500);

  // Step 1: Embed the question
  let embeddingResponse: { data: number[][] };
  try {
    embeddingResponse = await env.AI.run("@cf/baai/bge-base-en-v1.5", {
      text: [question],
    }) as { data: number[][] };
  } catch (err) {
    console.error("Embedding generation failed:", err);
    return Response.json({ error: "Failed to process your question" }, { status: 503 });
  }

  // Step 2: Search Vectorize
  let searchResults: Awaited<ReturnType<typeof env.VECTORIZE.query>>;
  try {
    searchResults = await env.VECTORIZE.query(
      embeddingResponse.data[0],
      { topK: 3, returnMetadata: "all" }
    );
  } catch (err) {
    console.error("Vectorize query failed:", err);
    return Response.json({ error: "Failed to search knowledge base" }, { status: 503 });
  }

  // Step 3: Build context
  const context = searchResults.matches
    .filter((match) => match.score > 0.5)
    .map((match) => match.metadata?.text as string)
    .filter(Boolean)
    .join("\n\n");

  if (!context) {
    return Response.json({
      answer: "I could not find relevant information to answer that question. Try rephrasing or asking something else.",
      sources: [],
    });
  }

  // Step 4: Generate answer
  let aiResponse: { response: string };
  try {
    aiResponse = await env.AI.run("@cf/meta/llama-3.3-70b-instruct-fp8-fast", {
      messages: [
        {
          role: "system",
          content: "You are a helpful assistant. Answer the question using only the context provided. If the context does not contain enough information, say so.",
        },
        {
          role: "user",
          content: `Context:\n\({context}\n\nQuestion: \){question}`,
        },
      ],
      max_tokens: 256,
    }) as { response: string };
  } catch (err) {
    console.error("LLM generation failed:", err);
    return Response.json({ error: "Failed to generate an answer" }, { status: 503 });
  }

  // Step 5: Return answer with sources
  const sources = searchResults.matches
    .filter((match) => match.score > 0.5)
    .map((match) => match.metadata?.source as string)
    .filter(Boolean);

  return Response.json({
    answer: aiResponse.response,
    sources: [...new Set(sources)],
  });
}

What each error handling decision means:

• try/catch around request.json(): request.json() throws if the body is not valid JSON. Without this catch, a malformed request crashes your Worker with an unhandled 500 error. With it, the caller gets a clear 400 explaining what went wrong.

• Input validation before processing: You check that question exists, is a string, and is not empty before calling any external service. This prevents wasted AI calls on invalid input.

• .slice(0, 500) on the question: This caps the input length before it reaches the embedding model. Without it, a malicious caller could send a very long string designed to inflate your AI usage or hit Workers CPU limits.

• 503 for AI and Vectorize failures: HTTP 503 means "service temporarily unavailable." It signals to callers that the error is on the server side and the request can be retried.

• .filter(Boolean) on context: After mapping match.metadata?.text, some results may be undefined if metadata was stored without a text field. This filters them out before joining, preventing "undefined" from appearing in the context string you send to the LLM.

How to Test Error Handling

Deploy your updated Worker:

npx wrangler deploy

Test each error case:

# Missing secret on load endpoint — should return 401
curl -X POST https://rag-tutorial-simple.<your-subdomain>.workers.dev/load

# Invalid JSON — should return 400
curl -X POST https://rag-tutorial-simple.<your-subdomain>.workers.dev/query \
  -H "Content-Type: application/json" \
  -d 'not json'

# Empty question — should return 400
curl -X POST https://rag-tutorial-simple.<your-subdomain>.workers.dev/query \
  -H "Content-Type: application/json" \
  -d '{"question": ""}'

Performance and Cost Analysis

This section uses real production data from my vectorize-mcp-worker deployment. It uses the same architecture you just built, measured from Port Harcourt, Nigeria to Cloudflare's edge.

Real Performance Numbers

Here is what the pipeline actually costs in time on every request:

This covers embedding generation and vector search only – the retrieval layer. LLM generation adds 500-1500ms on top, which is why end-to-end response time typically runs 600-1600ms.

The embedding step and vector search dominate. Everything else is negligible. For context, a comparable setup using OpenAI embeddings and Pinecone would add two external API roundtrips on top of this, easily pushing total latency past 1 second.

These numbers come from a single-region measurement. Your actual latency will vary based on your location and Cloudflare's load at the time of the request. The architectural point holds regardless: co-locating everything on the edge eliminates inter-service network hops, which is where most latency in traditional RAG stacks comes from.

Real Cost Breakdown

For 10,000 searches per day (300,000 per month) with 10,000 stored vectors:

This stack:

Traditional alternatives for the same volume:

That is an 85-95% cost reduction depending on which alternative you compare against. For a bootstrapped startup adding semantic search, that difference is $1,500-2,000 per year.

Why the Cost Difference Is So Large

Traditional RAG stacks have three cost problems that compound each other.

The first is idle compute. A dedicated server or container running your embedding service costs money even when no searches are happening. Cloudflare Workers charge only for actual execution time.

The second is inter-service data transfer. Every time your application calls an external service for an embedding, then calls a separate service for a search, you're paying for two external API calls with metered pricing. In this stack, both operations happen inside Cloudflare's network at no additional transfer cost.

The third is minimum plan pricing. Pinecone's Standard plan costs \(50/month as a floor, regardless of how little you use it. Cloudflare's pricing scales from the \)5/month Workers Paid plan base.

When the Included Allocation Is Enough

For smaller usage levels, you may not pay beyond the $5/month Workers Paid base price:

• Workers: 10 million requests per month included

• Workers AI: generous daily neuron allocation included

• Vectorize: available on both Free and Paid plans, with a free allocation included

A side project, internal tool, or small business with under 3,000 searches per day will likely stay within the included allocations entirely.

The Trade-off to Know About

This cost advantage comes with one operational constraint worth understanding before you build: Vectorize does not work in local development mode.

When you run wrangler dev, your Worker runs locally but Vectorize calls fail. You have to deploy to Cloudflare to test your vector search. For most development workflows this means testing your query logic locally with mocked responses, then deploying to a staging environment for full integration tests.

This is a real friction point. It's the honest trade-off for having a managed vector database with no infrastructure to operate.

Conclusion

In this tutorial, you have built and deployed a production-ready RAG system on Cloudflare's edge network. Let's look at what you actually built and what it costs to run.

What You Built

Your completed system has three endpoints:

• GET /: health check confirming the Worker is running

• POST /load: loads your knowledge base into Vectorize, protected by a secret header

• POST /query: accepts a question, retrieves relevant context, and returns a grounded answer with sources

The full query pipeline runs in four steps on every request:

1. The question is converted to a 768-dimensional embedding using @cf/baai/bge-base-en-v1.5

2. Vectorize finds the three most semantically similar documents

3. Documents above the 0.5 similarity threshold are assembled into context

4. Llama 3.3 generates an answer using only that context

Everything runs on Cloudflare's infrastructure. No external API keys. No separate vector database subscription. No servers to manage.

What to Build Next

This tutorial covered the core RAG pattern. Here are four directions to take it further.

Add more documents

The knowledge base in this tutorial has 8 documents. A real system might have thousands. The loading pattern is identical: add documents to knowledge-base.ts, hit /load with your secret, and Vectorize handles the rest.

For very large knowledge bases, update handleLoad to batch documents in groups of 20-50 rather than upserting one at a time.

Improve chunking

Each document in this tutorial is a single short paragraph. Real-world documents like PDFs, articles, documentation pages need to be split into chunks before embedding. Chunk at natural boundaries like paragraphs and sentences, aim for 200-400 tokens per chunk, and include 50-token overlaps between chunks to preserve context across boundaries.

Add conversation history

The current system treats every query as independent. To support follow-up questions, store previous messages in a Cloudflare KV namespace and include the last 2-3 exchanges in the LLM messages array alongside the retrieved context.

Stream the response

For long answers, users stare at a blank screen until generation completes. Cloudflare Workers support streaming responses via TransformStream. Switching to streaming means the first tokens appear in under 100ms while the rest generates.

Consider dimensions vs reranking trade-offs

This tutorial uses bge-base-en-v1.5 at 768 dimensions. My production system uses bge-small-en-v1.5 at 384 dimensions. Testing showed upgrading from 384 to 768 dims only improved accuracy by about 2%, but doubled cost and latency.

Adding a reranker (@cf/baai/bge-reranker-base) gave a larger accuracy improvement than the dimension upgrade for a fraction of the cost. The exact improvement will vary by domain and query distribution — test both on your actual data before deciding. If you're optimizing for production, add a reranker before you increase dimensions.

The Complete Project

Clone and deploy in five commands:

git clone https://github.com/dannwaneri/rag-tutorial-simple
cd rag-tutorial-simple
npm install
npx wrangler vectorize create rag-tutorial-index --dimensions=768 --metric=cosine
npx wrangler secret put LOAD_SECRET
npx wrangler deploy

Then load your knowledge base:

curl -X POST https://<your-worker>.workers.dev/load \
  -H "X-Load-Secret: your-secret"

If you found this useful, the production system this tutorial is based on is open source at github.com/dannwaneri/vectorize-mcp-worker. It extends this foundation with hybrid search combining vector and BM25, multimodal support for searching images with AI vision, a reranker for more accurate results, and a live dashboard. It runs on the same Cloudflare stack you just built – Workers, Vectorize, Workers AI – plus D1 for document storage.

One difference you'll notice: the production system uses bge-small-en-v1.5 at 384 dimensions rather than the 768 dimensions in this tutorial. That is an intentional trade-off: the reranker adds more accuracy than the extra dimensions at lower cost. The jump from what you built today to that system is smaller than it looks.

You will build a production-ready AI chatbot widget that you can embed on any website with a single script tag. It’ll be similar to Intercom or Drift – but it’s completely free and under your control.

By the end, you will have a chatbot that:

• Streams AI responses in real-time for a natural typing effect

• Answers questions from your FAQ using RAG (Retrieval Augmented Generation)

• Remembers conversations across page reloads

• Supports dark and light modes

• Works on any website with one line of code

Table of Contents

• Prerequisites

• What You Will Build

• How to Set Up the Project

• How to Configure Wrangler

• How to Build the Backend Worker

• How to Set Up Tailwind CSS

• How to Build the Frontend Widget

• Create the Demo Page

• How to Run it in Your Local System

• How to Deploy to Cloudflare

• How to Embed the Widget on Any Website

• How to Customize Your Chatbot

• Conclusion

Prerequisites

Before you start, make sure you have:

• A Cloudflare account (the free tier works perfectly)

• Node.js version 18 or higher installed on your computer

• Basic knowledge of JavaScript

You do not need any prior experience with Cloudflare Workers.

What You Will Build

Your chatbot will have two main parts:

1. Backend Worker (src/index.js): Handles chat requests, manages sessions, and connects to AI

2. Frontend Widget (public/widget.js): The embeddable UI that users interact with

You will use four Cloudflare services:

• Workers AI: Powers the AI responses using Meta's Llama 3 model

• Vectorize: Stores and searches your FAQ for relevant context (this is the RAG part)

• KV: Persists conversation history between sessions

• Workers: Runs your serverless backend at the edge

How to Set Up the Project

First, create a new Cloudflare Workers project. Open your terminal and run the following command.

When it asks you for the programming language, select javascript, and when it asks, "Do you want to deploy your application?" select no, since we’re going to deploy at the end.

npm create cloudflare@latest ai-chatbot-widget -- --type=hello-world

Navigate into your new project directory:

cd ai-chatbot-widget

And install the required development dependencies:

npm install --save-dev tailwindcss autoprefixer postcss wrangler

Your project is now ready for development.

How to Configure Wrangler

Wrangler is Cloudflare's command-line tool for developing and deploying Workers. You need to configure it to use the required services.

A Cloudflare Worker is a serverless function that runs on Cloudflare's global edge network. Unlike traditional servers that run in a single location, Workers execute as close to your users as possible using more than 300 data centers worldwide. This results in faster response times and lower latency. You just write the JavaScript code, and Cloudflare takes care of all the infrastructure, scaling, and deployment.

Create Resources (One-Time Setup)

The following resources are created via the Wrangler CLI (recommended for automation).

First, install Wrangler (if you don’t have it already):

npm install -g wrangler

To login, use wrangler login. This command will open a Cloudflare browser tab where you will need to authorize.

Create a vectorize index (for RAG):

A vectorize index is a vector database that lets you perform semantic search. Instead of searching for exact keyword matches (like in traditional databases), Vectorize finds content based on meaning.

Here's how it works: You convert your FAQ questions and answers into numerical vectors (called embeddings) using an AI model. When a user asks a question, the chatbot converts that question into a vector and finds the FAQ entries with the most similar vectors. This is the "RAG" (Retrieval Augmented Generation) technique, which augments the AI's response with relevant context from your knowledge base.

npx wrangler vectorize create faq-vectors --dimensions=768 --metric=cosine

Create KV namespace (for session history):

KV (Key-Value) storage is Cloudflare's globally distributed database for storing simple data. Think of it like a giant dictionary: you store data using a key (the session ID) and retrieve it later using that same key.

For your chatbot, KV stores each user's conversation history. When a user returns to your website, the chatbot retrieves their session from KV and remembers what they talked about before.

npx wrangler kv namespace create CHAT_SESSIONS

Note the id from the output as you'll add it in the wrangler.jsonc file.

Create a file called wrangler.jsonc in your project root (you just need to replace YOUR_KV_NAMESPACE_ID with the ID that you received in the last step):

{
  "$schema": "node_modules/wrangler/config-schema.json",
  "name": "ai-chatbot-widget",
  "main": "src/index.js",
  "compatibility_date": "2025-12-23",
  "observability": {
    "enabled": true
  },
  "assets": {
    "directory": "./public",
    "binding": "ASSETS"
  },
  "ai": {
    "binding": "AI"
  },
  "vectorize": [
    {
      "binding": "VECTORIZE",
      "index_name": "faq-vectors"
    }
  ],
  "kv_namespaces": [
    {
      "binding": "CHAT_SESSIONS",
      "id": "YOUR_KV_NAMESPACE_ID"
    }
  ]
}

This configuration file tells Wrangler which Cloudflare services your Worker needs access to.

Let me explain the key bindings:

• ASSETS: Serves static files (like your widget JavaScript and CSS) from the public folder

• AI: Connects to Cloudflare's Workers AI for running machine learning models

• VECTORIZE: Links to your Vectorize index for storing and searching FAQ embeddings

• CHAT_SESSIONS: Connects to a KV namespace for storing conversation history

How to Build the Backend Worker

The backend Worker is the brain of your chatbot. It handles incoming chat messages, searches your FAQ for relevant context, sends the conversation to the AI, streams the response back to the user, and saves everything to KV for later.

Create the file src/index.js with this code:

/** AI Chatbot Widget - Cloudflare Worker */
const SYS = `You are a helpful customer support assistant. Be friendly, professional, and concise. Use the FAQ context to give accurate answers. If you don't know something, say so.`;
const TTL = 30*24*60*60;
const cors = { 'Access-Control-Allow-Origin': '*' };
const json = (d, s=200, h={}) => new Response(JSON.stringify(d), { status: s, headers: { 'Content-Type': 'application/json', ...cors, ...h } });
const cookie = r => r.headers.get('Cookie')?.match(/chatbot_session=([^;]+)/)?.[1];

async function faq(env, q) {
  try {
    const e = await env.AI.run('@cf/baai/bge-base-en-v1.5', { text: [q] });
    if (!e.data) return '';
    const r = await env.VECTORIZE.query(e.data[0], { topK: 3, returnMetadata: 'all' });
    return r.matches.map(m => `Q: ${m.metadata?.question}\nA: ${m.metadata?.answer}`).join('\n\n');
  } catch { return ''; }
}

async function chat(req, env) {
  if (req.method !== 'POST') return new Response('Method not allowed', { status: 405 });
  const { message } = await req.json();
  if (!message?.trim()) return json({ error: 'Message required' }, 400);
  let sid = cookie(req), isNew = !sid;
  let sess = sid ? await env.CHAT_SESSIONS.get(sid, 'json') : null;
  if (!sess) { sid = 'sess_' + crypto.randomUUID(); sess = { id: sid, messages: [], createdAt: Date.now(), updatedAt: Date.now() }; isNew = true; }
  sess.messages.push({ role: 'user', content: message.trim(), timestamp: Date.now() });
  const ctx = await faq(env, message);
  const msgs = [{ role: 'system', content: SYS + (ctx ? `\n\nFAQ:\n${ctx}` : '') }, ...sess.messages.slice(-10).map(m => ({ role: m.role, content: m.content }))];
  const stream = await env.AI.run('@cf/meta/llama-3-8b-instruct', { messages: msgs, stream: true });
  let full = '';
  const { readable, writable } = new TransformStream({
    transform(chunk, ctrl) {
      for (const ln of new TextDecoder().decode(chunk).split('\n'))
        if (ln.startsWith('data: ') && ln.slice(6) !== '[DONE]') try { full += JSON.parse(ln.slice(6)).response || ''; } catch {}
      ctrl.enqueue(chunk);
    },
    async flush() {
      if (full) { sess.messages.push({ role: 'assistant', content: full, timestamp: Date.now() }); sess.updatedAt = Date.now(); await env.CHAT_SESSIONS.put(sid, JSON.stringify(sess), { expirationTtl: TTL }); }
    }
  });
  stream.pipeTo(writable);
  return new Response(readable, { headers: { 'Content-Type': 'text/event-stream', 'Cache-Control': 'no-cache', ...cors, ...(isNew ? { 'Set-Cookie': `chatbot_session=${sid}; Path=/; HttpOnly; SameSite=Lax; Max-Age=${TTL}` } : {}) } });
}

async function seed(req, env) {
  if (req.method !== 'POST') return new Response('Method not allowed', { status: 405 });
  const faqs = [
    ['How long does shipping take?', 'Standard 5-7 days, Express 2-3 days, Same-day in select areas.'],
    ['What is your return policy?', '30-day returns for unused items. Electronics 15 days if defective.'],
    ['Do you offer free shipping?', 'Yes! Orders over $50 get free standard shipping.'],
    ['How can I track my order?', 'Check your email for tracking or log into your account.'],
    ['What payment methods do you accept?', 'Visa, Mastercard, Amex, PayPal, Apple Pay, Google Pay.'],
    ['Do you have a warranty?', 'All products have manufacturer warranty. Extended plans available.'],
    ['Can I cancel my order?', 'Within 1 hour if not processed. Otherwise return after delivery.'],
    ['Do you ship internationally?', 'Yes, 50+ countries. 7-14 days. Duties paid by customer.'],
  ];
  try {
    const vecs = await Promise.all(faqs.map(async ([q,a], i) => {
      const e = await env.AI.run('@cf/baai/bge-base-en-v1.5', { text: [q+' '+a] });
      return { id: `faq-${i+1}`, values: e.data?.[0] || [], metadata: { question: q, answer: a } };
    }));
    await env.VECTORIZE.upsert(vecs);
    return json({ success: true, count: faqs.length });
  } catch { return json({ error: 'Seed failed' }, 500); }
}

export default {
  async fetch(req, env) {
    const p = new URL(req.url).pathname;
    if (req.method === 'OPTIONS') return new Response(null, { headers: { ...cors, 'Access-Control-Allow-Methods': 'GET,POST,OPTIONS', 'Access-Control-Allow-Headers': 'Content-Type' } });
    if (p === '/api/chat') return chat(req, env);
    if (p === '/api/history') { const s = cookie(req); return json({ messages: s ? (await env.CHAT_SESSIONS.get(s, 'json'))?.messages || [] : [] }); }
    if (p === '/api/seed') return seed(req, env);
    if (p === '/api/health') return json({ status: 'ok' });
    return env.ASSETS.fetch(req);
  }
};

Let me break down the key parts of this code:

• Session management: The cookie function extracts the session ID from the user's browser cookies. When a user first chats, the Worker generates a unique session ID, stores it in an HTTP-only cookie, and saves the conversation history to KV. On subsequent visits, the Worker retrieves the session and continues the conversation.

  RAG with Vectorize: The faq function implements RAG. It converts the user's question into a vector embedding using the BGE model, then queries Vectorize for the three most similar FAQ entries. This relevant context is added to the AI prompt, helping the AI give accurate, grounded answers instead of making things up.

  Streaming responses: The chat function uses a TransformStream to process the AI response as it streams. Each token is passed through to the client immediately, creating a natural typing effect. When the stream ends, the complete response is saved to KV.

  Seeding FAQs: The seed function populates your FAQ database. It converts each question-answer pair into a vector embedding and stores it in Vectorize. You only need to call this once after deploying.

Now that your backend is ready, let's build the frontend. But first, you need to set up Tailwind CSS to style your widget.

How to Set Up Tailwind CSS

Your chatbot widget needs to look polished and professional. To achieve this, you will use Tailwind CSS which is a utility-first CSS framework that lets you style elements directly in your HTML using small, single-purpose classes like bg-black, rounded-full, and shadow-lg.

Why Tailwind? Well, traditional CSS requires you to write separate stylesheets and invent class names. Tailwind eliminates this overhead by providing pre-built utility classes. This is especially useful for an embeddable widget because all the styles are self-contained and won't conflict with the host website's CSS.

Create the file tailwind.config.js in your project root:

tail/** @type {import('tailwindcss').Config} */
module.exports = {
  content: ['./public/**/*.{html,js}'],
  darkMode: 'class',
  theme: { extend: {} },
  plugins: []
};

This configuration tells Tailwind to scan all HTML and JavaScript files in the public folder for class names. The darkMode: 'class' setting enables dark mode toggling by adding a dark class to the widget container.

Create the source CSS file at src/input.css:

@tailwind base;
@tailwind components;src/input.css;
@tailwind utilities;

This file imports Tailwind's base styles, component classes, and utility classes. When you build, Tailwind will scan your code and generate a minimal CSS file containing only the classes you actually use.

Update your package.json with build scripts:

{
    "name": "ai-chatbot-widget",
    "version": "1.0.0",
    "private": true,
    "scripts": {
        "build:css": "npx tailwindcss -i ./src/input.css -o ./public/styles.css --minify",
        "deploy": "npm run build:css && wrangler deploy",
        "dev": "npm run build:css && wrangler dev"
    },
    "devDependencies": {
        "autoprefixer": "^10.4.23",
        "postcss": "^8.5.6",
        "tailwindcss": "^3.4.19",
        "wrangler": "^4.56.0"
    }
}

The build:css script compiles and minifies your Tailwind CSS. The deploy and dev scripts automatically build the CSS before starting the development server or deploying.

With styling ready to go, let's build the widget that users will actually interact with.

How to Build the Frontend Widget

The frontend widget is a self-contained JavaScript file that creates the entire chat interface. When someone adds your script to their website, it automatically creates the chat bubble button, the chat window, and handles all the interactive functionality.

Create the file public/widget.js:

/**
 * AI Chatbot Widget - Embeddable Script
 * Usage: <script src="https://your-domain.com/widget.js"></script>
 */
(function () {
  'use strict';
  const C = {
    u: window.CHATBOT_BASE_URL || '',
    t: window.CHATBOT_TITLE || 'AI Assistant',
    p: window.CHATBOT_PLACEHOLDER || 'Message...',
    g: window.CHATBOT_GREETING || '👋 Hi! How can I help you today?'
  };
  let open = 0, msgs = [], typing = 0, menu = 0;
  let dark = matchMedia('(prefers-color-scheme:dark)').matches;
  const $ = id => document.getElementById(id);
  const tog = (e, c, on) => e.classList.toggle(c, on);
  function init() {
    const l = document.createElement('link');
    l.rel = 'stylesheet';
    l.href = C.u + '/styles.css';
    document.head.appendChild(l);
    const d = document.createElement('div');
    d.id = 'cb';
    d.innerHTML = `
      <button id="cb-btn" class="fixed bottom-6 right-6 w-14 h-14 bg-black rounded-full shadow-2xl flex items-center justify-center cursor-pointer hover:scale-110 transition-all z-[99999]">
        <svg id="cb-o" class="w-6 h-6 text-white" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2">
          <path d="M21 11.5a8.38 8.38 0 01-.9 3.8 8.5 8.5 0 01-7.6 4.7 8.38 8.38 0 01-3.8-.9L3 21l1.9-5.7a8.38 8.38 0 01-.9-3.8 8.5 8.5 0 014.7-7.6 8.38 8.38 0 013.8-.9h.5a8.48 8.48 0 018 8v.5z"/>
        </svg>
        <svg id="cb-x" class="w-6 h-6 text-white absolute opacity-0 scale-50 transition-all" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2">
          <path d="M6 18L18 6M6 6l12 12"/>
        </svg>
      </button>
      <div id="cb-w" class="fixed bottom-24 right-6 w-[400px] h-[600px] rounded-2xl shadow-2xl flex flex-col overflow-hidden z-[99999] opacity-0 scale-95 pointer-events-none transition-all origin-bottom-right bg-white dark:bg-gray-900">
        <!-- Header -->
        <div class="flex items-center justify-between px-5 py-4 border-b bg-white dark:bg-gray-900 border-gray-100 dark:border-gray-800">
          <div class="flex items-center gap-3">
            <div class="w-10 h-10 bg-black rounded-full flex items-center justify-center">
              <span class="text-white font-bold text-lg">C</span>
            </div>
            <h3 class="font-semibold text-gray-900 dark:text-white">${C.t}</h3>
          </div>
          <div class="relative">
            <button id="cb-m" class="p-2 hover:bg-gray-100 dark:hover:bg-gray-800 rounded-full">
              <svg class="w-5 h-5 text-gray-500" viewBox="0 0 24 24" fill="currentColor">
                <circle cx="12" cy="5" r="1.5"/><circle cx="12" cy="12" r="1.5"/><circle cx="12" cy="19" r="1.5"/>
              </svg>
            </button>
            <div id="cb-d" class="hidden absolute right-0 top-full mt-2 w-44 bg-white dark:bg-gray-800 rounded-xl shadow-xl border border-gray-100 dark:border-gray-700 py-1 z-50">
              <button id="cb-th" class="w-full px-4 py-2 text-left text-sm text-gray-700 dark:text-gray-200 hover:bg-gray-50 dark:hover:bg-gray-700 flex items-center gap-2">
                <svg id="cb-s" class="w-4 h-4 hidden" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><circle cx="12" cy="12" r="5"/></svg>
                <svg id="cb-n" class="w-4 h-4" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><path d="M21 12.79A9 9 0 1111.21 3 7 7 0 0021 12.79z"/></svg>
                <span id="cb-tt">Dark Mode</span>
              </button>
              <button id="cb-cl" class="w-full px-4 py-2 text-left text-sm text-gray-700 dark:text-gray-200 hover:bg-gray-50 dark:hover:bg-gray-700 flex items-center gap-2">
                <svg class="w-4 h-4" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2">
                  <path d="M3 6h18M19 6v14a2 2 0 01-2 2H7a2 2 0 01-2-2V6m3 0V4a2 2 0 012-2h4a2 2 0 012 2v2"/>
                </svg>
                Clear Chat
              </button>
            </div>
          </div>
        </div>
        <!-- Messages -->
        <div id="cb-ms" class="flex-1 overflow-y-auto px-5 py-4 space-y-4 bg-gray-50 dark:bg-gray-950"></div>
        <!-- Typing Indicator -->
        <div id="cb-ty" class="hidden px-5 pb-2 bg-gray-50 dark:bg-gray-950">
          <div class="flex items-center gap-2 text-gray-400 text-sm">
            <div class="flex gap-1">
              <span class="w-2 h-2 bg-gray-400 rounded-full animate-bounce"></span>
              <span class="w-2 h-2 bg-gray-400 rounded-full animate-bounce" style="animation-delay:.15s"></span>
              <span class="w-2 h-2 bg-gray-400 rounded-full animate-bounce" style="animation-delay:.3s"></span>
            </div>
            Thinking...
          </div>
        </div>
        <!-- Input -->
        <form id="cb-f" class="flex items-center gap-3 px-4 py-4 border-t bg-white dark:bg-gray-900 border-gray-100 dark:border-gray-800">
          <input id="cb-i" type="text" class="flex-1 px-4 py-3 bg-gray-50 dark:bg-gray-800 border border-gray-200 dark:border-gray-700 rounded-full text-sm text-gray-900 dark:text-white placeholder-gray-400 focus:outline-none focus:ring-2 focus:ring-gray-200 dark:focus:ring-gray-600" placeholder="${C.p}" autocomplete="off"/>
          <button type="submit" id="cb-se" class="p-3 hover:bg-gray-100 dark:hover:bg-gray-800 rounded-full disabled:opacity-50">
            <svg class="w-5 h-5 text-gray-600 dark:text-gray-300" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2">
              <path d="M22 2L11 13M22 2L15 22L11 13L2 9L22 2Z"/>
            </svg>
          </button>
        </form>
      </div>`;
    document.body.appendChild(d);
    bind();
    load();
    theme();
  }
  function bind() {
    $('cb-btn').onclick = flip;
    $('cb-f').onsubmit = send;
    $('cb-m').onclick = e => { e.stopPropagation(); menu = !menu; tog($('cb-d'), 'hidden', !menu); };
    $('cb-th').onclick = () => { dark = !dark; theme(); menu = 0; tog($('cb-d'), 'hidden', 1); };
    $('cb-cl').onclick = () => { msgs = []; draw(); menu = 0; tog($('cb-d'), 'hidden', 1); };
    document.onclick = () => menu && (menu = 0, tog($('cb-d'), 'hidden', 1));
  }
  function theme() {
    tog($('cb'), 'dark', dark);
    $('cb-tt').textContent = dark ? 'Light Mode' : 'Dark Mode';
    tog($('cb-s'), 'hidden', !dark);
    tog($('cb-n'), 'hidden', dark);
  }
  function flip() {
    open = !open;
    const w = $('cb-w'), o = $('cb-o'), x = $('cb-x');
    tog(w, 'opacity-0', !open);
    tog(w, 'scale-95', !open);
    tog(w, 'pointer-events-none', !open);
    tog(w, 'opacity-100', open);
    tog(w, 'scale-100', open);
    tog(o, 'opacity-0', open);
    tog(o, 'scale-50', open);
    tog(x, 'opacity-0', !open);
    tog(x, 'scale-50', !open);
    tog(x, 'opacity-100', open);
    tog(x, 'scale-100', open);
    if (open) {
      $('cb-i').focus();
      if (!msgs.length) add('assistant', C.g);
    }
  }
  function add(r, c) {
    msgs.push({ role: r, content: c });
    draw();
  }
  function esc(t) {
    const d = document.createElement('div');
    d.textContent = t;
    return d.innerHTML.replace(/\n/g, '<br>');
  }
  function draw() {
    $('cb-ms').innerHTML = msgs.map((m, i) => m.role === 'user'
      ? `<div class="flex justify-end">
          <div class="bg-black text-white rounded-2xl rounded-br-md px-4 py-3 max-w-[85%]">
            <div id="m${i}" class="text-sm whitespace-pre-wrap">${esc(m.content)}</div>
          </div>
        </div>`
      : `<div class="flex justify-start">
          <div class="bg-white dark:bg-gray-800 text-gray-900 dark:text-gray-100 rounded-2xl rounded-bl-md px-4 py-3 max-w-[85%] border border-gray-200 dark:border-gray-700 shadow-sm">
            <div class="flex items-center gap-2 mb-2">
              <div class="w-6 h-6 bg-black rounded-full flex items-center justify-center">
                <span class="text-white font-bold text-xs">C</span>
              </div>
              <span class="text-sm font-medium text-gray-700 dark:text-gray-300">${C.t}</span>
            </div>
            <div id="m${i}" class="text-sm leading-relaxed whitespace-pre-wrap">${esc(m.content)}</div>
          </div>
        </div>`
    ).join('');
    $('cb-ms').scrollTop = $('cb-ms').scrollHeight;
  }
  async function send(e) {
    e.preventDefault();
    const m = $('cb-i').value.trim();
    if (!m || typing) return;
    add('user', m);
    $('cb-i').value = '';
    $('cb-se').disabled = 1;
    typing = 1;
    tog($('cb-ty'), 'hidden', 0);
    try {
      const r = await fetch(C.u + '/api/chat', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({ message: m }),
        credentials: 'include'
      });
      if (!r.ok) throw 0;
      const rd = r.body.getReader();
      const dc = new TextDecoder();
      let t = '', idx = null;
      while (1) {
        const { done, value } = await rd.read();
        if (done) break;
        for (const ln of dc.decode(value, { stream: 1 }).split('\n')) {
          if (!ln.startsWith('data: ')) continue;
          const d = ln.slice(6);
          if (d === '[DONE]') continue;
          try {
            const p = JSON.parse(d);
            if (p.response) {
              t += p.response;
              if (idx === null) {
                tog($('cb-ty'), 'hidden', 1);
                typing = 0;
                msgs.push({ role: 'assistant', content: t });
                idx = msgs.length - 1;
                draw();
              } else {
                msgs[idx].content = t;
                const el = $('m' + idx);
                if (el) el.innerHTML = esc(t);
              }
              $('cb-ms').scrollTop = $('cb-ms').scrollHeight;
            }
          } catch {}
        }
      }
    } catch {
      tog($('cb-ty'), 'hidden', 1);
      typing = 0;
      add('assistant', 'Sorry, an error occurred.');
    } finally {
      $('cb-se').disabled = 0;
      typing = 0;
      tog($('cb-ty'), 'hidden', 1);
    }
  }
  async function load() {
    try {
      const r = await fetch(C.u + '/api/history', { credentials: 'include' });
      if (r.ok) {
        const d = await r.json();
        if (d.messages?.length) {
          msgs = d.messages;
          draw();
        }
      }
    } catch {}
  }
  document.readyState === 'loading'
    ? document.addEventListener('DOMContentLoaded', init)
    : init();
})();

The widget uses an IIFE (Immediately Invoked Function Expression) to avoid polluting the global namespace. Here are the key functions:

• init(): Creates the widget HTML and injects it into the page

• bind(): Sets up all event listeners

• theme(): Toggles dark/light mode

• flip(): Opens and closes the chat window with animations

• draw(): Renders all messages

• send(): Handles message submission with streaming

• load(): Loads chat history from the server

The streaming handler in send() is particularly important. It reads the AI response chunk by chunk and updates the UI as each token arrives. Instead of re-rendering the entire message list on each token (which would cause visual flashing), it updates only the content of the current message element. This creates a smooth typing effect.

Now you need a simple page to test everything before deploying.

Create the Demo Page

The demo page serves as a testing ground during development and a showcase for your widget. When you or your users visit your deployed Worker URL directly, they will see this page with the chatbot widget already integrated.

Create public/index.html: This demo page will be for your internal testing.

<!DOCTYPE html>
<html lang="en">

<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>AI Chatbot Widget Demo</title>
  <link rel="stylesheet" href="/styles.css">
</head>

<body class="min-h-screen bg-gradient-to-br from-indigo-500 to-purple-600 flex items-center justify-center p-8">
  <div class="text-center text-white">
    <h1 class="text-4xl font-bold mb-4">AI Chatbot Widget</h1>
  </div>
  <script>    window.CHATBOT_BASE_URL = ''; window.CHATBOT_TITLE = 'Support'; window.CHATBOT_GREETING = "👋 Hi! I'm here to help with your questions!";  </script>
  <script src="/widget.js"></script>
</body>

</html>

This minimal page displays a title and loads the chatbot widget. The CHATBOT_BASE_URL is set to an empty string because when served from the same Worker, relative URLs work automatically. This is the exact same code someone would use to embed the widget on their own website, just with their own base URL instead.

With all the code in place, you are ready to deploy your chatbot to Cloudflare.

How to Run it in Your Local System

Once all the files are added, run the command npm run dev to see how the chat widget looks in http://localhost:8787:

How to Deploy to Cloudflare

Deployment is a single command. Run:

npm run deploy

This command first builds your Tailwind CSS, then deploys everything to Cloudflare. After deployment completes, you will see a URL like https://ai-chatbot-widget.YOUR-SUBDOMAIN.workers.dev.

in my case URL is https://ai-chatbot-widget.mv.workers.dev/

How to Seed the FAQ Database

Before your chatbot can answer questions from your FAQ, you need to populate the Vectorize index. Run this command (replace the URL with your actual deployment URL):

curl -X POST https://ai-chatbot-widget.YOUR-SUBDOMAIN.workers.dev/api/seed

You should see this response:

{"success":true,"count":8}

This means eight FAQ entries have been converted to vectors and stored in Vectorize. Your chatbot is now live and ready to answer questions!

Visit your deployment URL to test it out. Try asking about shipping, returns, or payment methods. The chatbot will respond using the FAQ context you just seeded.

Your chatbot is now live and ready to answer questions. You can check the Cloudflare dashboard to view the deployment. (The screenshot below is from the Cloudflare dashboard.)

How to Embed the Widget on Any Website

Now for the exciting part: adding your chatbot to any website. All it takes is two script tags before the closing </body> tag:

<script>
  window.CHATBOT_BASE_URL = 'https://ai-chatbot-widget.YOUR-SUBDOMAIN.workers.dev';
  window.CHATBOT_TITLE = 'Your Company';
  window.CHATBOT_GREETING = '👋 How can I help you today?';
</script>
<script src="https://ai-chatbot-widget.YOUR-SUBDOMAIN.workers.dev/widget.js"></script>

Replace YOUR-SUBDOMAIN with your actual Cloudflare Workers subdomain.

Or you can also open your Cloudflare deployment URL for testing.

Configuration Options

You can customize the widget using these variables:

How to Customize Your Chatbot

Your chatbot is working, but you probably want to tailor it to your specific use case. Here are the most common customizations.

How to Add Your Own FAQs

Open src/index.js and find the seed function. Replace the sample FAQs with your own question-answer pairs:

const faqs = [
  ['Your question here?', 'Your answer here.'],
  ['Another question?', 'Another answer.']
  // Add more Q&A pairs
];

Then redeploy with npm run deploy and call the /api/seed endpoint again to update your vector database.

How to Change the AI Personality

Edit the SYS constant at the top of src/index.js:

const SYS = `You are a friendly assistant for [Your Company].
You help customers with [your main services].
Always be helpful and professional.`;

This system prompt shapes how the AI responds to users.

How to Style the Widget

All styles use Tailwind CSS classes in widget.js. To change the appearance:

• Colors: Change bg-black to your brand color

• Size: Adjust w-[400px] h-[600px] for the chat window dimensions

• Position: Modify bottom-6 right-6 for placement

Conclusion

Congratulations! You have built a complete AI chatbot widget that rivals expensive SaaS solutions like Intercom and Drift. Your chatbot streams AI responses in real-time, answers questions based on your FAQ using RAG, and remembers conversations across sessions—all for free.

Here is a quick recap of what you built:

• A backend Worker that handles chat, sessions, and FAQ search

• A frontend widget that can be embedded on any website

• Integration with Workers AI for intelligent responses

• Vectorize for semantic FAQ search

• KV for persistent conversation history

The Cloudflare stack offers generous free tiers that should cover most use cases:

• Workers: 100,000 requests per day

• Workers AI: 10,000 neurons per day

• Vectorize: 5 million vector operations per month

• KV: 100,000 reads and 1,000 writes per day

For most websites, you can run this chatbot completely free.

The source code for this project is available on GitHub.

By the end, you'll have a fully functional authentication system with Astro actions, magic link authentication using Supabase, bot protection via Cloudflare Turnstile, protected routes and middleware, and secure session management.

Table of Contents

• Prerequisites

• Understanding the Technologies

  • What is Astro?

  • What are Astro Actions?

  • What is Supabase?

  • What is Cloudflare Turnstile?

• Understanding SSR Authentication

  • SSR vs. SPA Authentication

• Why Protect Auth Forms?

• Part 1: How to Set Up the Backend

  • Set Up Supabase Backend

  • Set Up Cloudflare Turnstile

• Part 2: How to Set Up the Frontend

  • Create the Astro Project

  • Configure Astro for SSR

  • Install Supabase Dependencies

  • Configure Environment Variables

• Part 3: How to Set Up Supabase SSR

  • Create the Supabase Client

  • Create Middleware for Route Protection

• Part 4: How to Build the User Interface

  • Update the Layout

  • Create the Sign-In Page

  • Create the Protected Page

• Part 5: How to Set Up Astro Actions

  • Create the Authentication Actions

  • Create the Code Exchange API Route

• Part 6: How to Test Your Application

• Notes and Additional Resources

  • Useful Documentation

  • Complete Code Repository

Prerequisites

This tutorial assumes you are familiar with:

• Web development frameworks

• Basic authentication flows

• Basic Backend-as-a-Service (BaaS) concepts

Understanding the Technologies

What is Astro?

Astro is a UI-agnostic web framework that renders server-first by default. It can be used with any UI framework, including Astro client components.

What are Astro Actions?

Astro actions allow you to write server-side functions that can be called without explicitly setting up API routes. They provide many useful utilities that simplify the process of running server logic and can be called from both client and server environments.

What is Supabase?

Supabase is an open-source Backend-as-a-Service that builds upon Postgres. It provides key features such as authentication, real-time capabilities, edge functions, storage, and more. Supabase offers both a hosted version for easy scaling and a self-hostable version for full control.

What is Cloudflare Turnstile?

Turnstile is Cloudflare's replacement for CAPTCHAs, which are visual puzzles used to differentiate between genuine users and bots. Unlike traditional CAPTCHAs, which are visually clunky, annoying, and sometimes difficult to solve, Turnstile detects malicious activity without requiring users to solve puzzles, while providing a better user experience.

Understanding SSR Authentication

Server-side rendered (SSR) auth refers to handling authentication on the server using a cookie-based authentication method.

The flow works as follows:

1. The server creates a session and stores a session ID in a cookie sent to the client

2. The browser receives the cookie and automatically includes it in future requests

3. The server uses the cookie to determine if the user is authenticated

Since browsers cannot modify HTTP-only cookies and servers cannot access local storage, SSR authentication requires careful management to prevent security risks such as session hijacking and stale sessions.

SSR vs. SPA Authentication

Single-Page Applications (SPAs), like traditional React apps, handle authentication on the client side because they don't have direct access to a server. SPAs typically use JWTs stored in local storage, cookies, or session storage, sending these tokens in HTTP headers when communicating with servers.

Why Protect Auth Forms?

Authentication protects sensitive resources from unauthorized access, making auth forms primary targets for bots and malicious actors. Taking extra precautions is important for maintaining security.

Part 1: How to Set Up the Backend

Set Up Supabase Backend

First, you'll need a Supabase account. Create a project, then:

1. Go to the Authentication tab in the sidebar

2. Click the Sign In / Up tab under Configuration

3. Enable user sign-ups

4. Scroll down to Auth Providers and enable email (disable email confirmation for this tutorial)

Set Up Cloudflare Turnstile

1. Log in or register for a Cloudflare account

2. Click the Turnstile tab in the sidebar

3. Click the "Add widget" button

4. Name your widget and add "localhost" as the hostname

5. Leave all other settings as default, and create the widget

After creating the widget, copy the secret key and add it to your Supabase dashboard:

1. Go back to Supabase Authentication settings

2. Navigate to the Auth Protection tab under Configuration

3. Turn on Captcha protection

4. Choose Cloudflare as the provider

5. Paste your secret key

Part 2: How to Set Up the Frontend

Create the Astro Project

Next, you will need to create an Astro project. Open your preferred IDE or Text editor’s integrated terminal and run the following command to scaffold an Astro project in a folder named “ssr-auth.” Feel free to use any name you like.

npm create astro@latest ssr-auth

Follow the provided prompts and choose a basic template to start with. When it’s done, change into the folder, then run npm install to install dependencies, followed by npm run dev to start the server, and your site will be available at localhost:4321.

Configure Astro for SSR

Set Astro to run in SSR mode by adding output: "server", to the defineConfig function found in the astro.config.mjs file at the root of the folder.

Next, add an adapter to create a server runtime. For this, use the Node.js adapter by running this command in a terminal: npx astro add node. This will add it and automatically make all relevant changes.

Finally, add Tailwind for styling. Run this command in a terminal window: npx astro add tailwind. Follow the prompts, and it will make any changes necessary.

At this stage, your astro.config.mjs should look like this:

// @ts-check
import { defineConfig } from "astro/config";
import node from "@astrojs/node";
import tailwindcss from "@tailwindcss/vite";

// https://astro.build/config
export default defineConfig({
  output: "server",
  adapter: node({
    mode: "standalone",
  }),
  vite: {
    plugins: [tailwindcss()],
  },
});

Install Supabase Dependencies

You can do this by running the following command:

npm install @supabase/supabase-js @supabase/ssr

Configure Environment Variables

Create a .env file in the project root and add the following. Remember to replace with your actual credentials:

SUPABASE_URL=<YOUR_URL>
SUPABASE_ANON_KEY=<YOUR_ANON_KEY>
TURNSTILE_SITE_KEY=<YOUR_TURNSTILE_SITE_KEY>

You can get the Supabase values from the dashboard:

💡Note: In Astro, environment variables accessed on the client side must be prefixed with 'PUBLIC'. But since we're using Astro actions that run on the server, the prefix is not required.

Part 3: How to Set Up Supabase SSR

Create the Supabase Client

Create src/lib/supabase.ts:

import { createServerClient, parseCookieHeader } from "@supabase/ssr";
import type { AstroCookies } from "astro";

export function createClient({
    request,
    cookies,
}: {
    request: Request;
    cookies: AstroCookies;
}) {
    const cookieHeader = request.headers.get("Cookie") || "";

    return createServerClient(
        import.meta.env.SUPABASE_URL,
        import.meta.env.SUPABASE_ANON_KEY,
        {
            cookies: {
                getAll() {
                    const cookies = parseCookieHeader(cookieHeader);
                    return cookies.map(({ name, value }) => ({
                        name,
                        value: value ?? "",
                    }));
                },
                setAll(cookiesToSet) {
                    cookiesToSet.forEach(({ name, value, options }) =>
                        cookies.set(name, value, options)
                    );
                },
            },
        }
    );
}

This sets up Supabase to handle cookies in a server-rendered application and exports a function that takes the request and cookies object as input. The function is set up like this because Astro has three ways to access request and cookie information:

• Through Astro’s global object, which is only available on Astro pages.

• Through AstroAPIContext object, which is only available in Astro actions.

• Through APIContext which is a subset of the global object and is available through API routes and middleware.

So the createClient function accepts the request and cookies objects separately to make it flexible and applicable in the various contexts in which it may be used.

Create Middleware for Route Protection

Next, create a middleware.ts file in the src folder and paste this into it:

import { defineMiddleware } from "astro:middleware";
import { createClient } from "./lib/supabase";

export const onRequest = defineMiddleware(async (context, next) => {
    const { pathname } = context.url;

    console.log("Middleware executing for path:", pathname);

    const supabase = createClient({
        request: context.request,
        cookies: context.cookies,
    });

    if (pathname === "/protected") {
        console.log("Checking auth for protected route");

        const { data } = await supabase.auth.getUser();

        // If no user, redirect to index
        if (!data.user) {
            return context.redirect("/");
        }
    }

    return next();
});

This middleware checks for an active user when accessing the protected route and redirects unauthenticated users to the index page.

Part 4: How to Build the User Interface

Update the Layout

First, update src/layouts/Layout.astro to include the Turnstile script. Add this just above the closing </head> tag:

<script
    src="https://challenges.cloudflare.com/turnstile/v0/api.js"
    async
    defer>
</script>

Create the Sign-In Page

Replace the contents of src/pages/index.astro:

---
import Layout from "../layouts/Layout.astro";
import { createClient } from "../lib/supabase";
import "../styles/global.css";

const supabase = createClient({
    request: Astro.request,
    cookies: Astro.cookies,
});

const { data } = await supabase.auth.getUser();

if (data.user) {
    return Astro.redirect("/protected");
}

const apiKey = import.meta.env.TURNSTILE_SITE_KEY;
---

<Layout>
    <section class="flex flex-col items-center justify-center m-30">
        <h1 class="text-4xl text-left font-bold mb-12">Sign In to Your Account</h1>
        <form id="signin-form" class="flex flex-col gap-2 w-1/2">
            <label for="email" class="">Enter your email</label>
            <input
                type="email"
                name="email"
                id="email"
                placeholder="youremail@example.com"
                class="border border-gray-500 rounded-md p-2"
                required
            />
            <div class="cf-turnstile" data-sitekey={apiKey}></div>
            <button
                type="submit"
                id="sign-in"
                class="bg-gray-600 hover:bg-gray-700 p-2 rounded-md text-white font-bold w-full cursor-pointer disabled:bg-gray-500 disabled:hover:bg-gray-500 disabled:cursor-not-allowed"
                >Sign In</button
            >
        </form>
    </section>
</Layout>

Here, the frontmatter creates a Supabase server client and then uses it to check if we have an active user. It redirects based on this information. This works because the front matter runs on the server side, and the project is set to server output.

The template displays a simple form with an email input. To complete it, add this below the closing </Layout> tag:

<script>
    import { actions } from "astro:actions";

    declare global {
        interface Window {
            turnstile?: {
                reset: () => void;
            };
        }
    }

    const signInForm = document.querySelector("#signin-form") as HTMLFormElement;
    const formSubmitBtn = document.getElementById("sign-in") as HTMLButtonElement;

    signInForm?.addEventListener("submit", async (e) => {
        e.preventDefault();
        formSubmitBtn.disabled = true;
        formSubmitBtn.textContent = "Signing in...";

        try {
            const turnstileToken = (
                document.querySelector(
                    "[name='cf-turnstile-response']"
                ) as HTMLInputElement
            )?.value;

            if (!turnstileToken) {
                throw new Error("verification_missing");
            }

            const formData = new FormData(signInForm);
            formData.append("captchaToken", turnstileToken);

            const results = await actions.signIn(formData);

            if (!results.data?.success) {
                if (results.data?.message?.includes("captcha protection")) {
                    alert("Verification failed. Please try again.");
                    if (window.turnstile) {
                        window.turnstile.reset();
                    }
                    formSubmitBtn.disabled = false;
                    formSubmitBtn.textContent = "Sign In";
                    return;
                } else {
                    alert("Oops! Could not sign in. Please try again");
                    formSubmitBtn.disabled = false;
                    formSubmitBtn.textContent = "Sign In";
                    return;
                }
            }

            formSubmitBtn.textContent = "Sign In";
            alert("Please check your email to sign in");
        } catch (error) {
            if (window.turnstile) {
                window.turnstile.reset();
            }
            formSubmitBtn.disabled = false;
            formSubmitBtn.textContent = "Sign In";
            console.log(error);
            alert("Something went wrong. Please try again");
        }
    });
</script>

This adds some vanilla JavaScript that calls the SignIn Upon form submission. This action provides user feedback through alerts and manages the button’s text and disabled state. This effectively adds client-side interactivity to the page.

Create the Protected Page

Create src/pages/protected.astro:

---
import Layout from "../layouts/Layout.astro";
import { createClient } from "../lib/supabase";
import "../styles/global.css";

const supabase = createClient({
    request: Astro.request,
    cookies: Astro.cookies,
});

const { data } = await supabase.auth.getUser();
---

<Layout>
    <section class="flex flex-col items-center justify-center m-30">
        <h1 class="text-4xl text-left font-bold mb-12">You are logged in!</h1>
        <p class="mb-6">Your user Id: {data.user?.id}</p>
        <button
            id="sign-out"
            class="bg-gray-600 hover:bg-gray-700 px-4 py-2 rounded-md text-white font-bold cursor-pointer disabled:bg-gray-500 disabled:hover:bg-gray-500 disabled:cursor-not-allowed"
            >Sign Out</button
        >
    </section>
</Layout>

<script>
    import { actions } from "astro:actions";
    const signOutBtn = document.getElementById("sign-out") as HTMLButtonElement;

    signOutBtn?.addEventListener("click", async (e) => {
        e.preventDefault();
        signOutBtn!.disabled = true;
        signOutBtn!.textContent = "Signing out...";

        try {
            const results = await actions.signOut();

            if (!results.data?.success) {
                signOutBtn!.disabled = false;
                signOutBtn!.textContent = "Sign Out";
                return alert("Oops! Could not sign Out. Please try again");
            }
            return window.location.reload();
        } catch (error) {
            signOutBtn.disabled = false;
            signOutBtn.textContent = "Sign Out";
            console.log(error);
            return alert("Something went wrong. Please try again");
        }
    });
</script>

This page retrieves the user data server-side in the front matter and displays it in the template, along with a sign-out button.

The JavaScript in the script tags handle calling the sign-out action, user feedback, and button state, as in the index.astro page.

Part 5: How to Set Up Astro Actions

Create the Authentication Actions

Finally, add an actions folder in the src folder and create an index.ts file to hold our logic. Paste the following into it:

import { defineAction, type ActionAPIContext } from "astro:actions";
import { z } from "astro:schema";
import { createClient } from "../lib/supabase";

const emailSignUp = async (
    {
        email,
        captchaToken,
    }: {
        email: string;
        captchaToken: string;
    },
    context: ActionAPIContext
) => {
    console.log("Sign up action");
    try {
        const supabase = createClient({
            request: context.request,
            cookies: context.cookies,
        });

        const { data, error } = await supabase.auth.signInWithOtp({
            email,
            options: {
                captchaToken,
                emailRedirectTo: "http://localhost:4321/api/exchange",
            },
        });

        if (error) {
            console.error("Sign up error", error);
            return {
                success: false,
                message: error.message,
            };
        } else {
            console.log("Sign up success", data);
            return {
                success: true,
                message: "Successfully logged in",
            };
        }
    } catch (err) {
        console.error("SignUp action other error", err);
        return {
            success: false,
            message: "Unexpected error",
        };
    }
};

export const server = {
    signIn: defineAction({
        accept: "form",
        input: z.object({
            email: z.string().email(),
            captchaToken: z.string(),
        }),
        handler: async (input, context) => {
            return emailSignUp(input, context);
        },
    }),
    signOut: defineAction({
        handler: async (_, context) => {
            const supabase = createClient({
                request: context.request,
                cookies: context.cookies,
            });
            const { error } = await supabase.auth.signOut();
            if (error) {
                console.error("Sign out error", error);
                return {
                    success: false,
                    message: error.message,
                };
            }
            return {
                success: true,
                message: "Successfully signed out",
            };
        },
    }),
};

This action handles both sign-in and sign-out methods. A Supabase server instance is created during the sign-in method, and the magic link method is used for sign-in. It passes a redirect URL, which we have yet to create, and handles any errors that may occur.

It also passes the token verification, allowing Supabase to perform verification on our behalf, eliminating the need to call Cloudflare’s verify APIs directly.

The sign-out method calls Supabase’s sign-out method and handles any potential errors.

The redirect URL refers to an API route that exchanges the code from the email Supabase sends for a session that Supabase handles.

Create the Code Exchange API Route

Create src/pages/api/exchange.ts:

import type { APIRoute } from "astro";
import { createClient } from "../../lib/supabase";

export const GET: APIRoute = async ({ request, cookies, redirect }) => {
    const url = new URL(request.url);
    const code = url.searchParams.get("code");

    if (!code) {
        return redirect("/");
    }

    const supabase = createClient({ request, cookies });
    const { error } = await supabase.auth.exchangeCodeForSession(code);

    if (error) {
        console.error("Error exchanging code for session:", error);
        return redirect("/404");
    }

    return redirect("/protected");
};

This grabs the code from the URL in the magic link sent, creates a server client, and calls the exchangeCodeForSession method with the code. It handles any error by redirecting to Astro’s built-in not-found page.

Otherwise, it will redirect to the protected page as Supabase handles the session implementation details.

Part 6: How to Test Your Application

Start your development server: npm run dev

Visit the provided localhost URL. You should see the sign-in page with the Turnstile widget:

If you try to access the /protected page, it will redirect you back to this view until you sign in. Now, sign in, and you should get an email with a link that will redirect you to the /protected page. This is what you should see:

And with that, you've successfully built a comprehensive auth system that leverages Astro actions, Supabase auth, and Cloudflare Turnstile's bot protection. This setup provides a secure, user-friendly authentication experience while protecting your application from malicious actors.

Notes and Additional Resources

Useful Documentation

• Supabase's advanced guide to SSR

• Supabase SSR package

• Astro Cookies documentation

• Supabase PKCE flow documentation

• Astro Actions documentation

• Get started with Turnstile

Complete Code Repository

The complete code for this project is available on GitHub:

• Base authentication setup

• With Cloudflare Turnstile

We are currently living in a fast-paced world, where time is money for everyone. People expect their favorite websites to load lightning-fast. A slow loading speed will not only make them go to the competitor but will also hurt the website's ranking in the SERP.

But the main question is, who’s the culprit? Those extra bits and bytes that almost every site contains. These are unnecessary code files, unoptimized images, and many more. But by following the right approach, you can easily strip away these inefficiencies and achieve excellent loading speed.

In this article, I will be discussing that approach in detail, so stick around with me till the very end.

Table of Contents

• Why Does Loading Speed Matter?

  • Google Ranking Factor

  • Impact on User Experience

  • Negative Brand Perception

  • Retaining Mobile Users

• How to Remove Extra Bits & Bytes from the Website – Different Strategies

  • Perform Code Optimization

  • Image & Media Optimization

  • Manage Plugins & Scripts

  • Server & Hosting Upgrades

• Tools That You Can Use to Streamline the Process

  • Minifier

  • TinyPNG

  • PNG to WebP Converter

  • Google PageSpeed Insight

  • Cloudflare

• Wrapping Up

Why Does Loading Speed Matter?

There are several reasons why the loading speed of a website is considered essential. Here are some of the major ones.

1. Google Ranking Factor:

Website loading speed is a confirmed ranking factor. This means that search engines like Google definitely consider the loading time when evaluating a website’s quality. Usually, the ideal loading speed is between 0 and 2 seconds. However, 3 seconds is also sometimes acceptable.

In case your site does not fulfill this criteria, then there is a high probability that it may receive a penalty from Google. This will result in lower rankings in the targeted niche – which no webmaster or business wants.

2. Impact on User Experience:

A slow loading speed is capable of single-handedly destroying the entire user experience. When the website does not load quickly in front of the visitor, they may close it and move on to another site to find the required information, product, or service.

This will decrease the number of user engagements and increase the overall bounce rate of the site. And a high bounce rate increases the chances of facing a penalty from Google.

3. Negative Brand Perception:

For online businesses or brands, their authority and image are everything. When their official site takes too much time to load, it ultimately damages the brand’s perception or credibility in their minds. They will think about how you can deliver a top-notch service or product when you aren’t able to properly manage a website.

This negative impression will not only reduce customer engagement but also conversions.

4. Retaining Mobile Users:

Mobile contributes to 58% of the global internet traffic. It is also true mobile networks often have slow internet speed issues as compared to Wi-Fi. This can be especially true for people living in rural areas. So, that’s why you should always prioritize loading speed to efficiently retain mobile users.

How to Remove Extra Bits & Bytes from the Website – Different Strategies

Here are some of the most proven strategies you can utilize to remove extra bits and bytes from your websites.

1. Perform Code Optimization:

Excessive HTML, CSS, and JavaScript can greatly slow down a website. Due to the large code file, the host server will have to transfer more packets to the client browser, ultimately resulting in slow loading.

To resolve this issue, it is always recommended to perform code optimization. The most widely known and used technique for this purpose is minification. It refers to the process of removing all the:

• Unnecessary characters

• White spaces

• Line breaks

• Comments

• Unused elements.

But you’ll want to make sure that the code works as before, even after minification.

Optimizing code boosts application performance by reducing execution time and resource consumption. Refactor inefficient loops, minimize database queries, and leverage caching to enhance speed. You can use profiling tools to identify bottlenecks and streamline functions for smoother, faster performance.

To demonstrate better, below I have discussed an example:

Unoptimized JavaScript Code:

greet(name) {
    if (!name) {
        console.log("Hello, Guest!");
    } else {
        console.log("Hello, " + name + "!");
    }
}
greet("John");

Minified Version:

function greet(n){console.log("Hello, "+(n||"Guest")+"!")}greet("John");

As you can see, I created the minified version by removing all the line breaks and whitespaces. Apart from this, I used shortened variables, like “n” instead of “Name.” Finally, I also replaced the If Else statement with a shorter n || "Guest" expression.

This is how you can easily condense the entire HTML, CSS, and JavaScript code of your website, and enhance the overall loading speed.

Just keep in mind that there are multiple downsides of code minification. For instance, it significantly impacts code readability and can cause challenges in debugging and maintenance. So use this approach judiciously.

2. Image & Media Optimization:

Apart from code, unoptimized images, logo files and other media files are often the main culprits behind the slow loading speed of a website. This means that you also need to optimize them as well. There are numerous things you can do in this regard.

First of all – you should reduce the image size in terms of storage. It is generally recommended that each picture should be less than 500 KB in size. But note that this size can vary depending on the use case.

It’s also a good idea to choose next-generation picture formats like WebP instead of typical ones like JPEG or PNG. When it comes to video files, it’s also helpful if you go with the embedded ones from platforms like YouTube.

Now, let us explain all this with a proper example (Before & After).

Let’s say that a website uses a 2MB JPEG image for its blog post. Its optimization process will involve the following steps:

• Resize the image first. The recommended dimensions are 1200x800.

• Compress the image size using image compression tools (we’ll discuss one such tool later in this article)

• Now, convert the JPEG file into WebP format.

• Add alternative text before publishing

After optimization:

• The image file size will now be reduced to KBS somewhere around 120Kb.

• Your website will experience better loading speed as well as an improved user experience.

One more tip that you can consider is lazy loading. This means only loading the images and videos when they are about to be consumed.

By taking care of these few things, you can efficiently optimize images and media files to achieve faster loading speeds.

3. Manage Plugins & Scripts:

Your website may contain unused plugins and scripts that can cause bloat. So, to remove the extra bits and bytes, it is essential to perform regular check-ins.

First, make sure you deactivate and delete all the plugins that aren’t needed. Then, start exploring more lightweight alternatives for plugins that you are actively using. If you find any, go for them and uninstall the bulky ones to improve performance and enhance security, especially for processes like identity verification. Ensure you’re using the latest, most optimized version..

For example, Revolution Slider is a heavy plugin. It loads large scripts and images on every page, even when not needed. This ultimately affects the overall website speed. Some of its lightweight alternatives that you might consider for this include Smart Slider 3, or any other CSS-based slider.

Next comes script management. Here you should first limit any third-party scripts, such as excessive code tracking, social media widgets, and embedded content. Apart from this, don’t forget to totally disable scripts on the pages where they aren’t required.

One useful example here is Google Analytics which loads tracking scripts on every page, increasing the request time. To fix this issue, you can use Google Tag Manager to load the scripts only when they are needed.

Additionally, you can use no-code workflow automation tools like Zapier, Make, or Uncanny Automator which help streamline processes by reducing reliance on heavy plugins and scripts.

4. Server & Hosting Upgrades:

This is the final strategy that you can consider. Your hosting provider plays a key role in deciding the loading speed of the website. So, it’s a good idea to upgrade your hosting plan and get it from a reputable and credible service.

Also, do not forget to enable server-side compression. Doing so will automatically reduce the file sizes before transmission. Optimizing database performance is equally crucial, as database observability enables database pipeline analytics, helping to identify inefficiencies, reduce query execution time, and enhance overall site responsiveness.

Also, take steps to optimize the database queries. You can do this by removing unnecessary data while also caching data mechanisms. There are also specialized plugins available for this like WP-Optimize. It effectively cleans up all the unnecessary data saving valuable time and effort.

You should also start caching queries. Store all the frequent ones in memory. This will significantly reduce database load.

SELECT * FROM products WHERE category = 'Laptops' CACHE;

This prevents the server from re-executing the same query repeatedly.

So, these are some of the proven strategies you can apply to eliminate additional bits & bytes from the website to achieve faster loading.

Tools That You Can Use to Streamline the Process

To simplify the process of optimizing website loading speed, you can consider utilizing the following tools.

1. Minifier

First of all, we have Minifier, a dedicated tool that is specifically designed to automate the code minification process with a single click. It is available for free and works for HTML, CSS, and JavaScript codes.

Besides this, the tool features a user-intuitive interface so that you can quickly navigate through it. The minifier is trained according to both development and minification to ensure maximum speed and accuracy in the output.

All you need to do is either paste or upload the code file into the tool, hit the “Minify” button, and get a condensed version. You can check out the below screenshot to get a better idea how it works.

Minify also offers a wide variety of other useful tools you can use if needed. Some notable options include JSON minifier and XML formatter, among others.

So now there is no need to spend time and effort on manually minifying your code for better loading speed. You can just use this tool and get the job done with a single click.

2. TinyPNG

Many of you may have heard of or even used this tool. It is an image compression tool that will help you effectively reduce your image sizes for optimization. The good thing is that TinyPNG perfectly preserves the original quality of the picture (in terms of resolution) even after the compression.

All you need to do is upload the required photo from your local storage, and the tool will automatically provide a compressed version. Don’t worry about the file format, as TinyPNG supports JPG, PNG, JPEG, and many more.

The tool even provides the percentage of how much the uploaded image was compressed, like -51%, and so on. It also mentions the size of the compressed photo in terms of KBs. So, in case you are not satisfied with the file size, you can further compress it.

3. PNG to WebP Converter:

As I mentioned earlier, I recommend using next-gen image formats like WebP instead of older formats when possible. Usually, the widely used format is PNG, but to seamlessly convert into WebP, you can use this PNG to WebP converter.

It’s available for free and does not ask for registration/signup. Simply visit the page and start performing conversions. The conversion is performed without causing any damage to the image’s quality and formatting.

The tool also offers many extra features. For instance, you can adjust both the image’s width and height. You can also set image quality (WebP compression level) if required. And it doesn’t stop here – you can even select the right fit for the photo from the following options:

• Max

• Crop

• Scale

4. Google PageSpeed Insight

How can you enhance the loading speed of the website when you don’t even know which elements are causing issues? For this purpose, Google PageSpeed Insight is the best solution. It is developed and managed by Google.

The tool effectively crawls the given page link and highlights all the issues that are causing slow loading. It even provides four different scores (0-100) for evaluation. These include:

• Performance

• Accessibility

• Best Practices

• SEO

The good thing is that Google PageSpeed Insights evaluates the page for both mobile and desktop users. The results are also provided separately. The areas of improvement are highlighted in red, along with the necessary instructions you can take. The good parts are marked with green.

By utilizing this tool, you can easily evaluate your website and then make efforts to improve the loading speed.

5. Cloudflare

Last but not least, Cloudflare is a good tool that helps enhance the loading speed of a website by using its global content delivery network (CDN). With this feature, it caches static content across different servers worldwide. This ultimately reduces the overall latency and improves loading speed for users in different locations.

Besides this, Cloudflare also offers a bunch of other features. For example, it automatically minifies HTML, CSS, and JavaScript files. It can even compress and convert images into next-gen formats, especially WebP.

It offers a robust DNS resolution that reduces lookup times and helps the page load faster. This feature also protects the site from DDoS attacks.

Wrapping Up

If you want to experience higher ranking and increased user engagement, then you need to optimize your website’s loading speed. The extra bits and bytes like code files, media, and so on can cause real hurdles – but don’t worry.

By using these strategies and tools, you’ll be able to speed up page loading in no time. I hope you found this article interesting and valuable.

But do you know you can do it for free? There is actually a way to do it, and besides the fact that having the professional email account is free, it will help you be more efficient, reliable and secure in your daily work.

In this article, you'll learn how to create and set up your own email address using Cloudflare and Mailgun to manage emails in Gmail. This means that you can send and receive emails directly in your Gmail inbox.

I've done this already for personal use and have taken screenshots of the entire process that you'll see in this article. So I'll share all the necessary steps you need to follow to set up your own email.

Let's figure out what you need to have before you start, what you are going to do, and how it will work.

What you need to have before you start

I assume that you already have a domain, let's call it "yourdomain.com". Specifically, you need to have accessibility to connect your domain with Cloudflare and setup DNS records there. A classic example of that is having a domain on some domain registrar (like GoDaddy, Namecheap), and adding your domain to Cloudflare by setting DNS records provided by Cloudflare on your domain registrar account.

Adding a domain to Cloudflare involves updating your domain's DNS nameservers to point to Cloudflare's nameservers. Once the domain is added, Cloudflare acts as an intermediary for web traffic, providing security features like DDoS protection, firewall, and SSL encryption, as well as performance enhancements through caching and content optimization.

If you haven't done that yet, here's the official video on YouTube on how to connect your domain to Cloudflare.

Additionally, Cloudflare manages DNS records for your domain, allowing you to control how traffic is routed and ensuring reliable delivery of services like email.
So, our work in this article will be focusing exactly on that: how to setup your domain on Cloudflare Email.

Cloudflare Email has been one of the services of Cloudflare since 2021, which can be used for free (as of now, at least).

The second assumption is that you have Gmail account, and you have access to its email settings. Simply, if you just have a regular "youremail@gmail.com" email, which isn't under the control of any administrator, then you have nothing to worry about. We'll explore and work on email settings later on.

What you are going to do

In simple words, you're going to create a custom email like "something@yourdomain.com", which you can use to send and receive emails using Gmail's platform. So you will be receiving and reading emails sent to "something@yourdomain.com" in Gmail, as well as sending emails from that custom email using Gmail.

You'll use Cloudflare Email for the email routing, and Mailgun's SMTP server for sending emails.

How it will work

When composing an email from Gmail with the sender set as "something@yourdomain.com", Gmail utilizes Mailgun's SMTP server through the provided credentials, transmitting the email. Mailgun then processes the message and forwards it to the recipient's email server, likely involving DNS lookups to find the recipient's server.

Emails sent to "something@yourdomain.com" are received by Cloudflare's email servers, configured via MX records in the domain's DNS settings. Cloudflare stores the received emails in the associated account, accessible through Gmail, which periodically connects to Cloudflare's servers (using IMAP or POP3 protocols) to retrieve new messages, enabling seamless access to incoming emails.

Email Routing on Cloudflare

Cloudflare Email Routing is designed to simplify the way you create and manage email addresses, without needing to keep an eye on additional mailboxes. With Email Routing, you can create any number of custom email addresses to use in situations where you do not want to share your primary email address, such as when you subscribe to a new service or newsletter. Emails are then routed to your preferred email inbox, without you ever having to expose your primary email address. (Cloudflare Docs)

Sign in to your Cloudflare account and navigate to the Dashboard.
Choose and click on the desired website. For me it's "boolfalse.com", as I want to create a custom email like "email@boolfalse.com".

Cloudflare: Websites

Navigate to Email Routing for the selected website.

Cloudflare: Email Routing

If you don't have email routing configured, you may see something similar to the screenshot above. Click "Get started". You may be able to create your own address to receive emails and take action.

We'll skip this without creating our own address because we'll do it manually.

Cloudflare: Custom Email

By default, email routing is disabled, so you need to enable it. Click the link to navigate to the Email Routing page.

Cloudflare: Email Routing

Submit it by clicking "Enable Email Routing".

Cloudflare: Enable Email Routing

You need to have three MX and one TXT records:

• Type: MX; Name: @; Mail Server: route1.mx.cloudflare.net; TTL: Auto; Priority: 69
• Type: MX; Name: @; Mail Server: route2.mx.cloudflare.net; TTL: Auto; Priority: 99
• Type: MX; Name: @; Mail Server: route3.mx.cloudflare.net; TTL: Auto; Priority: 40
• Type: TXT; Name: @; TTL: Auto; Content: _v=spf1 include:spf.mx.cloudflare.net ~all

You can see them at the bottom of the Email Routing page.

Cloudflare: DNS records for Email Routing

So, as already said, in the left menu, go to "DNS" -> "Records" and add the following records there.

Cloudflare: DNS records added

After creating these records, go to the Email Routing page again.

Here, you only need to have the records you just created. So if you have any other records, just delete them.

For example, I already had an unnecessary entry there that I should delete.

Cloudflare: existing records for Email Routing

Submit to delete existing unnecessary records.

Cloudflare: deleting unnecessary records

After removing unnecessary DNS records, you will see only the ones you need there.

You will now be able to enable email routing by clicking the "Add records and enable" button.

Cloudflare: Enable Email Routing

After enabling it you should see something like this:

Cloudflare: Email DNS records configured

How to Create a Custom Email on Cloudflare

Now go to the Routes tab and create an email by clicking the "Create address" button.

Cloudflare: Email Routing (enabled)

In this example, we'll create "email@boolfalse.com" email address, by adding "email" as a custom address, and a destination email address, where I'll be able to receive emails.

Cloudflare: Email Routing

You should see a notification about that.

Cloudflare: creating a custom email

You should also get an email for confirming this action.

Verifying the destination email

Go on and verify the email address.

Verify email address

Once you've verified the email address, you may get this page:

Cloudflare: custom email address is verified

You will probably get an email that you've verified your domain with Mailgun:

Notification about custom email address verification

How to Receive Emails in the Custom Email

Now, your email address is activated, and you can see that here:

Cloudflare: custom email address is active

At this point you can send emails to the custom email you just set up. In this case, it's "email@boolfalse.com".

Below is a test email sent from a different email.

Testing email receiving

You'll receive a test email to the custom email.

Test email has been received

Mailgun: Adding New Domain

You can now successfully receive emails, but you can't send emails from that custom email yet.

So, it's time to switch to the mail service provider. In our case, it will be Mailgun.
To do this, you just need to register and attach the card to your Mailgun account. After activating your account with the card attached, you can set up a domain for your email.

You don't have to worry about the card, because Mailgun does not charge for limited quantities. I think the amount it gives is quite suitable for a free package.
You can find the price packages in detail here.

Go to Sending -> Domains page, and click the "Add New Domain" button.

In our case it will be "mg.boolfalse.com", as Mailgun recommends that to be able to send emails from your root domain, that is: "email@boolfalse.com".

You should see that recommendation on the right in below image:

Mailgun: create a new domain

You can also select the domain region and DCIM key length, but you can leave everything as default.
I will leave DCIM key length as 1024 and "US" as a domain region.

After creating the domain, you may be shown some tips on how to verify your domain.

Mailgun: adding a new domain

Mailgun will give you two TXT records, two MX records and one CNAME record to add to your provider.

• Type: TXT; Name: _mailto._domainkey.mg.boolfalse.com_; TTL: Auto; Content:
• Type: TXT; Name: mg.boolfalse.com; TTL: Auto; Content: v=spf1 include:mailgun.org ~all
• Type: MX; Name: mg.boolfalse.com; Mail Server: mxa.mailgun.org; TTL: Auto; Priority: 10
• Type: MX; Name mg.boolfalse.com; Mail Server: mxb.mailgun.org; TTL: Auto; Priority: 10
• Type: CNAME; Name: email; Target: mailgun.org; TTL: Auto; Proxy Status: On

In our case, we will add them to Cloudflare.

Below is the first TXT record:

Mailgun: first TXT record for a new domain

Below is the second TXT record:

Mailgun: second TXT record for a new domain

Below is the first MX record:

Mailgun: first MX record for a new domain

Below is the second MX record:

Mailgun: second MX record for a new domain

After you've added two TXT and two MX records, you can check and verify them by clicking the "Verify DNS Records" button.

Mailgun: checking TXT and MX records for a new domain

Lastly, add CNAME record.

Mailgun: adding CNAME record for a new domain

You may see a warning icon on the left of the CNAME record. You don't need to worry about that. Here's what official documentation says about it:

If you recently added your domain to Cloudflare - meaning that your zone is in a pending state - you can often ignore this warning.
Once most domains becomes Active, Cloudflare will automatically issue a Universal SSL certificate, which will provide SSL/TLS coverage and remove the warning message.

After adding a CNAME record, you can check and verify it again by clicking the second "Verify DNS Records" button.

Mailgun: checking CNAME record for a new domain

If you have added all 5 records on the Cloudflare successfully, after clicking the verifying button, Mailgun will automatically redirect you to the Overview page.

Mailgun: 2 TXT, 2 MX and 1 CNAME records added for a new domain

It means you're ready to add a Sending API key on Mailgun.

Mailgun: Sending API key & SMPT User

Go to Sending -> Domain Settings page. Choose the Sending API keys tab at the top. You probably won't see any API keys there. You just need to create a new Sending API key.

Click "Add sending key" from the top right corner, and in the pop-up, fill the name of the key you're about to create.

Mailgun: creating a Sending API key

After pressing "Create sending key", you'll get the secret API key that you need to copy and save somewhere safe. After saving the key, you can just close the pop-up.

You should see the created key listed:

Mailgun: Sending API key created

You also need to create a new SMTP user in the Mailgun dashbaord.
Go to Sending -> Domain Settings page. Choose the SMTP credentials tab at the top and click the "Add new SMTP user" button on the top left corner. It will open up a pop-up.

Type user credentials there. In our case I'll create a user with the name "email". It will be like a login for your email on Gmail.

Mailgun: creating SMTP user

Once you create an SMTP user in Mailgun, you'll see it listed and a password for that user will be generated automatically. To get this password, copy it by clicking the "Copy" button in the pop-up notification in the lower right corner.

Mailgun: SMTP user created

Keep this in a safe place for future use. You will need this login and password to authenticate on Gmail.

You are now ready to set up email configurations with your email provider. In our case, we will do this in Gmail.

Open your Gmail account in your desktop browser and go to Settings by clicking the settings icon in the top right corner and click the "See all settings" button.

Mailgun: new domain is verified

Gmail Authentication with Mailgun SMTP Server

In the Gmail settings page choose the Accounts and Import tab and click on the "Add another email address" from the "Send mail as" section:

Gmail: Settings

It will open a pop-up for the authentication. Use the login and the password you just got by creating an SMTP user on Mailgun. Make sure to fill out the credentials correctly.

Gmail: authenticate a new user using a created SMTP server on Mailgun

Submit the form by clicking the "Add Account" button. It'll probably ask you to save the username/password in your browser. It's up to you.

And the last important thing here: it'll ask you to verify adding an account.

Gmail: authentication confirmation for a new user

For the verification, the confirmation email will be sent to your primary email.

Gmail: authentication verification email

You can either use the confirmation code to verify it using the pop-up window or simply follow the link provided in the confirmation email.

In this case, we'll click on a link which will open the page, where you'll be asked to confirm. Click on "Confirm" and simply close the previously opened pop-up window without worrying.

Gmail: verifying the authentication

Now you're ready to send and receive emails from the custom email you just created.

For sending an email from the custom email, you just need to choose that email as a sender email:

Gmail: sending emails

That's it!

An additional thing that may be useful to you is that you can set the custom email address you just created as the default address for sending emails from Gmail.

You can set this on the settings page in the "Send mail as" section:

Gmail: Settings (default sender)

I hope this guide will be a good resource for setting up your custom email.

Conclusion

In this article, you learned how to set up your own email to manage emails in Gmail using Cloudflare Email and Mailgun.

In conclusion, it is worth noting that the choice of tools is not mandatory, other tools can be used instead, but the basic idea and logic will be similar.

You can check out my website at: boolfalse.com

Feel free to share this article. 😇

You'll see how to not only build and deploy your app within minutes using just a few tools, but also how to auto-deploy any future changes you make through your GitHub account.

How to Get Started

To get started, you'll need the following tools:

1. The package manager npm and version control software Git
2. Your own (free) GitHub account and Cloudflare account

Create our React Project

To deploy a React application we first need to have one created.

Let's build a React app on our computer with the help of Create React App. We can do so by giving it the name "cloudflare-react":

npx create-react-app cloudflare-react

Create our Github Repository

And once our project been created successfully, let's go ahead and create a GitHub repository for it.

We use GitHub to be able to keep an online, easy-to-manage record of our individual projects. GitHub also allows other users to make improvements to our code through pull requests.

Cloudflare uses GitHub to keep track of all of our code and whenever we make changes.

To track our new React app, we create a new GitHub repository by going to github.com/new.

Next, we can simply add all of our files and commit them with a message that says what we are doing:

git add .
git commit -m "Deploy to Cloudflare Pages"

Next, we need to add the appropriate Git remote, used to push our committed code upstream to our new GitHub repo.

GitHub will tell you the command you need to include for your newly created repo. It should look something like this:

git remote add origin someurl

And finally, we can simply run git push -u origin master.

After we refresh our GitHub repo page, we should see all of our React project code, pushed to GitHub.

This is the first main requirement of deploying an application to Cloudflare pages – to have a React application living on GitHub.

Create a Cloudflare Account

Next, we go to Cloudflare to deploy our React project.

If you don't have a free Cloudflare account already, you can go to pages.cloudflare.com and hit "Sign up":

One main reason why you and most other developers would be interested in using Cloudflare pages, is that Cloudflare has a worldwide CDN. This allows for faster delivery of our deployed application.

Cloudflare also has resources such as DNS management, which is especially helpful if you want your application to have its own custom domain.

Link GitHub to Cloudflare Pages

The first time you visit Cloudflare pages you'll be prompted to create a project from your GitHub repository so you'll select the Connect GitHub account button:

Then you'll be asked to install and authorize Cloudflare pages.

This step allows us to choose what Cloudflare gets access to – whether we want to give it access to all of our repositories or only to select repositories:

If you want to deploy multiple projects in the future I'd recommend selecting all repositories.

As a result, Cloudflare will have the ability to access any code and deployments that we've made so it can be deployed to the web.

Deploy our React Project to Cloudflare Pages

Once we've given Cloudflare authorization to do so, we'll see a screen where we can choose what project from our GitHub repository we want to deploy:

In our case, we'll choose our "cloudflare-react" repo, after which we will hit Begin setup.

From there we can choose what project name we want our React app to have with Cloudflare. This project name is important because it determines the subdomain that it's going to be deployed to.

Since we chose "cloudflare-react", it will be deployed to cloudflare-react.pages.dev:

We can choose which branch to deploy, as well as the build settings.

Note that all we really have to do is choose what framework preset we're using. Cloudflare has a preset option for our framework – Create React App.

When we choose it, it's going to include the default settings for any Create React App project: to deploy the project by running the build command "npm run build" and the output directory (the folder to which our React code will be built upon running this build command) is named "build".

There are other helpful presets for any React application that's made with a framework like Next.js or Gatsby. You can use Cloudflare pages to deploy almost any type of React application you can think of.

Finally, we can hit the deploy button. The deployment process will take about four to five minutes the first time. Be patient, but be aware that any subsequent deploy is going to take a lot less time.

We do see some helpful logs about our project being built and the progress of our deployment. If there were an error in that process, we would see it in the logs and get some indication as what as to what we needed to fix.

Then to see our deployed project we can hit the Continue to Project button, hit "Visit Site" and we can see our app running on the URL: your-project-name.pages.dev.

Make Changes with Auto Deploys

While it was very easy to instantly deploy our React application to the web after we had it pushed to GitHub, the next step is to make changes to our app and redeploy it.

As you'll see, this auto-deploy (continuous integration) functionality has already been set up.

In the case of my application, I decided to install React Router DOM to add an about page. On the home page, I also added a link to the about page:

After I was done performing that change which you can see in the video above, I went through the same process of running git add ., git commit with a message about the changes that I made, and then git push.

After doing so, if we flip back to our Cloudflare pages dashboard, we can see that immediately Cloudflare has picked up this new deploy because it's linked to our GitHub account and can view any deploys or pull requests that were made to our repo.

As a result, it instantly re-deploys our app with the changes that we made. As our deploy is taking place, we can hit "View build" and can see specific information about this deploy, along with any logs.

As you will see, any change made after the initial deploy takes a lot less time (it only takes about a minute in total for the deploy to finish successfully). You will also see that it's given its own unique deploy hash at the beginning of our URL. This allows us to uniquely reference each deploy.

If we remove the hash, we see that the changes that we made are also deployed to our chosen project name: cloudflare-react.pages.dev.

Conclusion

I hope that this tutorial shows you just how easily it is to get started with the new Cloudflare pages. You can start deploying your React apps to it today to take advantage of their global CDN and all the additional features that Cloudflare has to offer.

Cloudflare pages is still quite new, but it offers a lot of tools already that are worth checking out. I'd highly recommend it as your deployment service for the next React app you want to share with the world.

Become a Professional React Developer

React is hard. You shouldn't have to figure it out yourself.

I've put everything I know about React into a single course, to help you reach your goals in record time:

Introducing: The React Bootcamp

It’s the one course I wish I had when I started learning React.

Click below to try the React Bootcamp for yourself:

Click to get started

You should read this if…

1. You want to setup custom redirects or other server configuration for free
2. You want to get your site on HTTPS but don’t know where to start
3. You’re overwhelmed with the amount of choices out there (like Netlify, Surge, BitBalloon, Now)

Why Github?

1. Easy to setup and get started with Github Pages
2. Instant deploys on pushing new code

Why Cloudflare?

1. It’s free
2. It comes with out-of-the-box support for SSL (HTTPS). (Here’s why HTTPS matters.)
3. Super simple DNS management
4. Ability to set browser cache expiration for assets
5. Auto minify your static assets
6. Custom page rules for setting up redirects, always HTTPS, etc.
7. HTTP2/SPDY for supported browsers
8. Allows for setting up HSTS (HTTP Strict Transport Security)

Before we get started you will need a few things:

1. A Github account
2. A Cloudflare account
3. Access to a custom domain. You can buy it from any Domain Name Registrar like: Namecheap, GoDaddy, BigRock, etc.

If all this piqued your interest, then let’s get started!

Step 1: Create Github repo with your code

Select the option Project Site to get started

• Go to https://pages.github.com
• Select the option Project Site to find the instructions on how to create a basic page from scratch or a custom theme

Step 2. Setup Github Pages for the repository

Go to Settings for your repository

Choose to serve your website from the master branch

Go to Settings for your repository. In the Github Pages section, choose the master branch to serve your website from. Once you’ve done that, you can go to https://_.gith_u_b.io/repository to see your website in action as shown below.

Step 3. Add custom domain

Add a custom domain for your website

Add the custom domain that you have bought and save it. Your website is now ready with your own custom domain ? WOOT! ✨

So, we have everything setup on Github. We’ll start with setting up Cloudflare to jazz up your website with all the powerful features I mentioned at the beginning of this post.

Step 4: Setup your domain on Cloudflare

Login to Cloudflare. If you are using it for the first time, you should see a screen like the image shown above. If you have used it before, you can click on the Add Site option in the navigation bar on the top right to add a new domain. Enter the domain you want to manage and click on Begin Scan.

Step 5: Setup DNS Records for your domain

Left: Setup DNS records for apex domain. It is denoted by @. Right: Final DNS record list

In this step, we inform Cloudflare to point our domain to the Github Pages server using two A Record DNS entries:

1. 192.30.252.153
2. 192.30.252.154

Once you have set this up, all requests to your custom domain i.e. yourcustomdomain.com will be routed to your website on Github on Step 3.

There’s one more step involved before we move on to the next stage. Oftentimes, you would want to use a subdomain like www for your website, i.e. www.yourcustomdomain.com For this, you will need to add a CNAME record DNS entry which will point your subdomain(www) to your apex domain(@).

Once you have set this up, all requests to your custom subdomain i.e. www.yourcustomdomain.com will be routed to your website on Github on Step 3.

NOTE: Don’t try to go access your custom domain right away. It won’t work. We have only done the Cloudflare to Github setup. We still have to do the DNS Registrar -> Cloudflare setup. This will come up in Step 7.

Click Continue to go to the next step.

Step 6: Choose the Free Cloudflare plan

The Free plan for Cloudflare provides a lot of sophisticated options as discussed in the Why Cloudflare? section at the beginning.

Click Continue to go to the next step.

Step 7: Update Nameservers on your DNS Registrar

Copy these two highlighted nameservers to your DNS registrar’s name server settings

Once you’re on this page, keep it open in one tab and open your DNS Registrar’s (the place from where your bought your domain) site in another. If you’re using one of the following registrar’s then the links to understand how to change Nameserver are:

1. Bigrock
2. Namecheap
3. GoDaddy

You need to replace the existing Nameservers in your Domain settings with the one’s on the Cloudflare page that is open in the other tab.

An example of how it would look like after you’ve updated your Nameserver settings in your DNS registrar

YASSS! You’ve successfully setup your custom domain to use Cloudflare as a DNS provider. You can go to the Overview option on the top and you will find that it is still waiting for your Nameserver change to be processed.

Left: Nameserver change is still being processed. Right: Nameserver change is processed!!

Once the Overview tab says Status: Active, you can now try to visit your site using your custom domain, AND IT SHOULD JUST WORK! ??

Step 8: Configure Minification

In the Speed setttings, in the Auto Minify section, choose the option to auto-minify everything: Javascript, CSS, HTML. This will be done by Cloudflare on-the-fly once and then cached. Whenever any of your assets change, Cloudflare will do this again for you.

The advantage of minification is that the size of the file delivered to your browser is a lot less since it strips off unwanted spaces and comments.

Step 9: Configure Browser Cache Expiration

Cache Expiration set to 1 month

If you scroll down on the same page as Auto Minify, you will find the Browser Cache Expiration section. It should be set to 30 days/1 month, ideally, for WebpageTest to not give you a warning. What this time indicates is that, once your site is loaded in any browser, then the browser will not request any assets for a second time until the Browser Cache time period expires for those assets.

_Example: The iphone.png image loads from your server for the first time (22.3KB in 349ms) All subsequent requests to fetch that resource are served from disk cache which means it is [instantaneously](http://www.softwaretestingclub.com/forum/topics/what-is-the-difference-between-disk-cache-memory-cache-browser?commentId=751045%3AComment%3A304464" rel="noopener" target="_blank" title="">almost <a href="https://www.reddit.com/r/explainlikeimfive/comments/3660ig/eli5what_is_the_difference_between_disk_caching/crb1c3i/" rel="noopener" target="blank" title=") available (in 5ms)

Before we move on to the next step, please check the Crypto settings on Cloudflare. It should say Active Certificate in the SSL section. (Note: Try reloading the page. Sometimes it doesn’t update). In the next two steps, we are going to make your site serve via HTTPS always. For that to work without any problems, it is important that you have an active certificate on Cloudflare.

The SSL section shows Authorizing Certificate after your Nameserver changes have been processed. Once an SSL certificate for you has been issued, this message will change to Active Certificate.

Step 10: Configure Page Rules

In this step, we are going to do two things:

1. Redirect all requests for www.yourcustomdomain.com to yourcustomdomain.com
2. Redirect all requests for http://yourcustomdomain.com to https://yourcustomdomain.com

Go to the Page Rules setting and click on Create Page Rule.

For handling the www.yourcustomdomain.com to yourcustomdomain.com redirect, replace tweetify.io with yourcustomdomain.com name. Click Save and Deploy.

For handling the http://yourcustomdomain.com to https://yourcustomdomain.com redirect, replace tweetify.io with yourcustomdomain.com name. Click Save and Deploy.

Step 11: Configure HSTS

Go to the Crypto settings and scroll down to the HTTP Strict Transport Security (HSTS) section. Click on Enable HSTS. This will ask you to acknowledge that you know what you are doing. Before you select I understand, let me tell you why we need to enable this setting:

If a user has opened your website in the past, from then onwards whenever the user tries to access your website, they will always be taken to the HTTPS version of your site. This makes your site load a little faster on subsequent visits because the HTTP to HTTPS redirect happens on the client and not via the Cloudflare Page Rule that we added in Step 10.

Once you go to the next step, you should enable all the settings as shown below. You can read more details about these options here and here

Screenshot of HSTS settings in Cloudflare

_Headers that are added by Cloudflare to requests for your domain after you setup HSTS [as shown above](#a96c" rel="noopener" target="blank" title=")

That’s it. You’re all set to show off your website to the world! ?? If you found this useful, please ❤️ it and share it.

Karan Thakkar is the Frontend Lead at Crowdfire - Your super-smart marketing sidekick. His article has been previously featured on The Huffington Post. He likes trying out new technologies in his spare time and has built Tweetify (using React Native) and Show My PR’s (using Golang).

Other articles written by him:

How I grew from 300 to 5k followers in just 3 weeks
_#GrowthHacking my Twitter account for @Crowdfire Twitter Premier League_blog.markgrowth.comUsing the Let’s Encrypt Certbot to get HTTPS on your Amazon EC2 NGINX box
_Let’s Encrypt is a new Certificate Authority which provides free SSL certificates (up to a certain limit per week). It…_medium.freecodecamp.com