CloudFlare(CF) CDN Worker Full Page Cache(FPC) Layer for Magento 2. It has become true. Now, it is Open Source and free. The original idea was the Shopify FPC cache from the CloudFlare CDN, AWS Cloud Front Lambda Edge S3 Buket, Akamai EdgeWorkers with Object Storage etc. and it is a part of our true Magento SaaS solution(Magneto)

Deployment

You can deploy the worker in several ways:

Deploy via Cloudflare Dashboard (Quick Start)

1. Create a Worker in Cloudflare Dashboard → Workers & Pages → Create Worker
2. Edit Code → Insert Code from Git → Connect to https://github.com/Genaker/CloudFlare_FPC_Worker
3. Configure KV binding and deploy
4. Add a route for your domain (e.g. *yoursite.com/*)

See the Installation section below for detailed steps.

Deploy via Wrangler CLI

If you use Wrangler:

git clone https://github.com/Genaker/CloudFlare_FPC_Worker.git
cd CloudFlare_FPC_Worker
npm install
cp wrangler.toml.example wrangler.toml   # if available
# Edit wrangler.toml with your KV namespace and account ID
npx wrangler deploy

Deploy via CI/CD (GitHub Actions, etc.)

You can add the worker to your CI pipeline. Example GitHub Actions step:

- name: Deploy Cloudflare Worker
  run: |
    npm install -g wrangler
    wrangler deploy
  env:
    CLOUDFLARE_ACCOUNT_ID: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
    CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}

Store your secrets in the repository settings and ensure your wrangler.toml has the correct KV namespace binding.

Deploy via Terraform

Use the cloudflare Terraform provider to deploy the worker as infrastructure-as-code:

terraform {
  required_providers {
    cloudflare = {
      source  = "cloudflare/cloudflare"
      version = "~> 4.0"
    }
  }
}

variable "cloudflare_account_id" {}
variable "cloudflare_api_token" {}

provider "cloudflare" {
  api_token = var.cloudflare_api_token
}

resource "cloudflare_workers_kv_namespace" "fpc_kv" {
  account_id = var.cloudflare_account_id
  title      = "fpc-cache"
}

resource "cloudflare_worker_script" "fpc" {
  account_id = var.cloudflare_account_id
  name       = "magento-fpc"
  content    = file("${path.module}/FPC.js")

  kv_namespace_binding {
    name         = "KV"
    namespace_id = cloudflare_workers_kv_namespace.fpc_kv.id
  }
}

resource "cloudflare_worker_route" "fpc_route" {
  zone_id     = var.cloudflare_zone_id
  pattern     = "*yoursite.com/*"
  script_name = cloudflare_worker_script.fpc.name
}

Run terraform init, terraform plan, then terraform apply. Ensure FPC.js and any required files are in the Terraform module path.

Deploy via Python (cloudflare Python SDK)

Use the cloudflare Python package to deploy programmatically:

from cloudflare import Cloudflare

api = Cloudflare(api_token="YOUR_API_TOKEN")
account_id = "YOUR_ACCOUNT_ID"

# Read worker script
with open("FPC.js", "r") as f:
    script_content = f.read()

# Create or update worker
api.workers.scripts.upload(
    account_id=account_id,
    script_name="magento-fpc",
    body={"script": script_content},
)

# Add KV binding (create namespace first via API or dashboard)
# api.workers.scripts.settings.update(...)

Install: pip install cloudflare. For full deployment including KV bindings and routes, use the Workers API endpoints for Workers Scripts, KV Namespaces, and Worker Routes.

How it works

The Edge Worker Magento full-page cache feature helps you optimize eCommerce performance by caching your Magento backend server's generated HTML or API response.

Integration Jest tests

All functionality is covered with the Jest integration tests. You can test your website and you rule as well. Running the test:

export TEST_URL="https://******.com/"
npm install
npm test

Run integration tests with Docker

TEST_URL=https://yoursite.com/ docker compose run --rm fpc-tests

Unit tests (Vitest + Miniflare)

Unit tests run locally without a live site. They use Miniflare to emulate the Cloudflare Workers runtime.

npm run test:unit

Or with Docker:

docker compose run --rm fpc-unit

Generate static HTML objects

Run next command

node generate.js

HTML CACHE VERSION

CF Edge Worker Magent Full-page cache intercepts incoming requests and checks if a cached version of the requested content is available in the CloudFlare locations or in the cache Reserve. This check for the cached version can have the following outcomes, depending on its state:

• If a cached version is found and it's not stale, then the cached content is served to the user. No request is made to the Magento Server.
• If a cached version is found and it is stale, then the cached content is served to the user. The CF worker is executed in the background and requests a new version of the page caches from the Magento backend server for future requests. CF FPC is revalidated from the server asynchronously after 5 minutes or so, but you can change the time and logic.
• If a cached version isn't found, the CF FPC worker sends a request to the Magento server to be used for future requests.

CF Worker “softpurge” the cache by changing cache Version stored in the KV(Key Value)storage. Cloud flare serve the stale content untill it will not be updayed asynchronously (in the background) fetches the new page. Cloud Front ignores any cache rules from Magento and has own logic which serve web pages from the CDN cache even if Magento 2 website is broken.

Now, you can set HTML_CACHE_VERSION via the Cloud Flare dashboard by adding the variable ENV_HTML_CACHE_VERSION. It will override the default cache version logic and can't be purged except to set a new version from the dashboard.

ENV VARIABLES

You can override many variables by setting the from the dashboard by adding ENV_ prefix to the var name:

Worker GET parameters:

• &cfw=false - disable Cloud worker, bypass all worker logic
• &cf-cdn=false - bypass Cloud Flare EDGE CDN cache, but R2 cache still works
• &r2-cdn=false - bypass R2 cache
• &cf-revalidate=true - revalidate URL in the cache
• &cf-delete=true - delete from the edge cache but not from R2
• &cf-purge - purge entire cache by changing cache version. called ONCE(1) - soft purge. TWICE(2) - hard purge.

Speculative Rules

Speculation is added to the worker response.

To Debug speculative rules, go to DevTools → Application → Speculative Load → Speculation:

Caching criteria

For CF FPC Worker to consider a response from a Magento backend as cacheable, the response must meet the following criteria:

• Be a response to a GET request
• Have a 2XX or 3XX status code.
• Have a public Cache-Control header set with a non-zero max-age, or s-maxage, value
• Url doesn't match the worker's blacklist

Aditional features

• URL Query String Filtering and sorting
• Traffic filtering and control
• Cache logic adjustment. You don't need any VCL now you can do everething in pure JavaScript
• Content manipulation
• Speculation rules prerender and prefetch
• Link header resource preload
• Custom CORS
• ESI (Edge Server Include - AJAX requests) blocks with auth and HTTPS support. Easy to use with microservices.
• GOD MOD - cache can't be invalidated. It can be but not easy.
• PWA installable APP

R2 and Cache Reserve

When R2 is configured (Ultra version), the worker can store and serve cached content from Cloudflare R2. This provides a persistent cache layer beyond the edge. The worker races R2 and the origin — whichever responds first is served. When the origin wins, the response is marked as server-first or r2-null-server in the R2-cache header. Both outcomes are valid; the cache is updated asynchronously.

Cache Reserve uses R2 under the hood and integrates with the worker for higher hit rates. Enable Cache Reserve in the Cloudflare dashboard to improve cache persistence.

Worker and CF cache limitations:

• The full-page cache is designed to work with the default magento cache, which is PHP Built-in FPC, FAST FPC (See repo: https://github.com/Genaker/FastFPC), or Varnish. You can try to use it as a main cache (see Cache Reserve), but it is not what it was designed for. *The main idea of the CF Worker FPC Cache is Magento 2 pages are always served from the CF cache with async revalidation.
• You can't clear the cache by page. You can clear the entire cache only. That is why you need a default magento cache. However, it is designed to work without any cache clears. The worker will update it asynchronously. You mark the entire cache stale by changing its version. To hard clear the cache, you need to change the version twice. CF Worker checks the previous cache version to see if it is a stale cache.

Installation

Navigation: Cloudflare Dashboard → Workers & Pages (or go to dash.cloudflare.com and select Workers & Pages from the sidebar).

It is better to Upgrade the plan to a Bundle of 5$ per month. It is better and has no limitations.

Bundle:

Workers features Includes 10 million requests per month 3

Up to 50ms CPU time per request Always lowest latency Key-value storage features 4 10 million read operations per month 1 million write, delete, list operations per month

Create KV (KeyValue) Storage to keep the cache version and some global settings

Path: Workers & Pages → KV → Create a namespace. (Alternatively: create the Worker first, then add a KV binding under Settings → Bindings; you can create a new namespace from there.)

Create Worker

Path: Workers & Pages → Create (or Create application) → Create Worker. If using Git: choose Clone and bootstrap a public repository and enter https://github.com/Genaker/CloudFlare_FPC_Worker, then Deploy.

Insert CF Worker FPC Code from The repo

Path: Edit Code → Insert Code from Git (or Connect to Git). Connect to https://github.com/Genaker/CloudFlare_FPC_Worker. If you created the worker from the Git repo in the previous step, skip this.

Configure Worker

Path: Your Worker → Settings → Variables and Secrets (for ENV vars) and Settings → Bindings (for KV).

Worker Variable name must be KV. KV name doesn't matter (Select from the drop-down)

R2 storage is not available in the open source version, only in the Ultra Version. Please contact for more details.

NOTE: OTHER_HOST is not required settings

Configure the OTHER_HOST variable with your actual domain (e.g. www.yoursite.com) to test the worker through the worker domain. This replaces the worker domain with your staging or prod domain so responses are fetched from your Magento server. This variable is not required for production.

NOTE: OTHER_HOST is not required settings

Set your website route and worker to trigger:

Path: Your Worker → Settings → Triggers (or Routes). Add route pattern e.g. *yoursite.com/* or yoursite.com/* (replace with your domain).

Done! Test it using Dev Console.

You can also exclude some page rules, such as static and media, from workers. It will save money on request.

Also, Enable CF Cache Reserve to increase edge cache HIT rate. To reduce CF costs, you can exclude media and static from the cache reserve. However, cache reserve is a nice stuff, and you can benefit from storing images in it.

![image](https://github.com/user-attachments/assets/0c1bc4df-483e-