Cloudflare Workers are a serverless platform that allows you to run JavaScript code in over 300 cities worldwide without configuring or maintaining infrastructure. Unlike traditional servers that run in a single location, Workers execute on the network edge, meaning your code runs physically close to your website visitors. This architecture provides incredible speed and scalability for dynamic operations.
When a request arrives at a Cloudflare data center for your website, it can be intercepted by a Worker before it reaches your GitHub Pages origin. The Worker can inspect the request, make decisions based on its properties like the user's country, device, or cookies, and then modify the response accordingly. It can fetch additional data from APIs, rewrite the URL, or even completely synthesize a response without ever touching your origin server. This model is perfect for a static site because it offloads dynamic computation from your simple hosting setup to a powerful, distributed edge network, giving you the best of both worlds: the simplicity of static hosting with the power of a dynamic application.
Workers operate in a constrained environment for security and performance. They are not full Node.js environments but use the V8 JavaScript engine. The free plan offers 100,000 requests per day with a 10ms CPU time limit, which is sufficient for many use cases like redirects or simple A/B tests. While they cannot write to a persistent database directly, they can interact with external APIs and Cloudflare's own edge storage products like KV. This makes them ideal for read-heavy, latency-sensitive operations that enhance a static site.
The easiest way to start with Workers is through the Cloudflare Dashboard. This interface allows you to write, test, and deploy code directly in your browser without any local setup. We will create a simple Worker that modifies a response header to see the end-to-end process.
First, log into your Cloudflare dashboard and select your domain. Navigate to "Workers & Pages" from the sidebar. Click "Create application" and then "Create Worker". You will be taken to the online editor. The default code shows a basic Worker that handles a `fetch` event. Replace the default code with this example:
addEventListener('fetch', event => {
event.respondWith(handleRequest(event.request))
})
async function handleRequest(request) {
// Fetch the response from the origin (GitHub Pages)
const response = await fetch(request)
// Create a new response, copying everything from the original
const newResponse = new Response(response.body, response)
// Add a custom header to the response
newResponse.headers.set('X-Hello-Worker', 'Hello from the Edge!')
return newResponse
}
This Worker proxies the request to your origin (your GitHub Pages site) and adds a custom header to the response. Click "Save and Deploy". Your Worker is now live at a random subdomain like `example-worker.my-domain.workers.dev`. To connect it to your own domain, you need to create a Page Rule or a route in the Worker's settings. This first step demonstrates the fundamental pattern: intercept a request, do something with it, and return a response.
One of the most powerful applications of Workers is conducting A/B tests without any client-side JavaScript or build-time complexity. You can split your traffic at the edge and serve different versions of your content to different user groups, all while maintaining blazing-fast performance.
The following Worker code demonstrates a simple 50/50 A/B test that serves two different HTML pages for your homepage. You would need to have two pages on your GitHub Pages site, for example, `index.html` (Version A) and `index-b.html` (Version B).
addEventListener('fetch', event => {
event.respondWith(handleRequest(event.request))
})
async function handleRequest(request) {
const url = new URL(request.url)
// Only run the A/B test for the homepage
if (url.pathname === '/') {
// Get the user's cookie or generate a random number (0 or 1)
const cookie = getCookie(request, 'ab-test-group')
const group = cookie || (Math.random() < 0.5 ? 'A' : 'B')
// If the user doesn't have a cookie, set one that lasts 30 days
if (!cookie) {
const response = await fetchAndSetCookie(request, group)
return response
}
// Serve the appropriate version based on the group
if (group === 'B') {
// Modify the request to fetch the B version
url.pathname = '/index-b.html'
const modifiedRequest = new Request(url, request)
return fetch(modifiedRequest)
}
// Else, serve Version A (the default index.html)
}
// For all other pages, fetch the original request
return fetch(request)
}
function getCookie(request, name) {
let result = null
const cookieString = request.headers.get('Cookie')
if (cookieString) {
const cookies = cookieString.split(';')
for (let cookie of cookies) {
const [cookieName, cookieValue] = cookie.split('=')
if (cookieName.trim() === name) {
result = cookieValue
}
}
}
return result
}
async function fetchAndSetCookie(request, group) {
const url = new URL(request.url)
if (group === 'B') {
url.pathname = '/index-b.html'
}
const modifiedRequest = new Request(url, request)
const response = await fetch(modifiedRequest)
// Clone the response to add the Set-Cookie header
const newResponse = new Response(response.body, response)
newResponse.headers.append('Set-Cookie', `ab-test-group=${group}; Max-Age=2592000; Path=/`)
return newResponse
}
This Worker checks if the user has a cookie assigning them to a group. If not, it randomly assigns them to group A or B and sets a long-lived cookie. Then, it serves the corresponding version of the homepage. This ensures a consistent experience for returning visitors.
While Page Rules can handle simple redirects, Workers give you programmatic control for complex logic. You can redirect users based on their country, time of day, device type, or whether they are a new visitor.
Imagine you are running a marketing campaign and want to send visitors from a specific country to a localized landing page. The following Worker checks the user's country and performs a redirect.
addEventListener('fetch', event => {
event.respondWith(handleRequest(event.request))
})
async function handleRequest(request) {
const url = new URL(request.url)
const country = request.cf.country
// Redirect visitors from France to the French homepage
if (country === 'FR' && url.pathname === '/') {
return Response.redirect('https://www.yourdomain.com/fr/', 302)
}
// Redirect visitors from Japan to the Japanese landing page
if (country === 'JP' && url.pathname === '/promo') {
return Response.redirect('https://www.yourdomain.com/jp/promo', 302)
}
// All other requests proceed normally
return fetch(request)
}
This is far more powerful than simple redirects. You can build logic that redirects mobile users to a mobile-optimized subdomain, sends visitors arriving from a specific social media site to a targeted landing page, or even implements a custom URL shortener. The `request.cf` object provides a wealth of data about the connection, including city, timezone, and ASN, allowing for incredibly granular control.
Workers can fetch data from multiple sources in parallel and combine them into a single response. This allows you to keep your site static while still displaying dynamic information like recent blog posts, stock prices, or weather data.
The example below fetches data from a public API and injects it into the HTML response. This pattern is more advanced and requires parsing and modifying the HTML.
addEventListener('fetch', event => {
event.respondWith(handleRequest(event.request))
})
async function handleRequest(request) {
// Fetch the original page from GitHub Pages
const orgResponse = await fetch(request)
// Only modify HTML responses
const contentType = orgResponse.headers.get('content-type')
if (!contentType || !contentType.includes('text/html')) {
return orgResponse
}
let html = await orgResponse.text()
// In parallel, fetch data from an external API
const apiResponse = await fetch('https://api.github.com/repos/yourusername/yourrepo/releases/latest')
const apiData = await apiResponse.json()
const latestReleaseTag = apiData.tag_name
// A simple and safe way to inject data: replace a placeholder
html = html.replace('', latestReleaseTag)
// Return the modified HTML
return new Response(html, orgResponse)
}
In your static HTML on GitHub Pages, you would include a placeholder like ``. The Worker fetches the latest release tag from the GitHub API and replaces the placeholder with the live data before sending the page to the user. This approach keeps your build process simple and your site easily cacheable, while still providing real-time data.
Personalizing content based on a user's location is a powerful way to increase relevance. With Workers, you can do this without any complex infrastructure or third-party services.
The following Worker customizes a greeting message based on the visitor's country. It's a simple example that demonstrates the principle of geographic personalization.
addEventListener('fetch', event => {
event.respondWith(handleRequest(event.request))
})
async function handleRequest(request) {
const url = new URL(request.url)
// Only run for the homepage
if (url.pathname === '/') {
const country = request.cf.country
let greeting = "Hello, Welcome to my site!" // Default greeting
// Customize greeting based on country
if (country === 'ES') greeting = "¡Hola, Bienvenido a mi sitio!"
if (country === 'DE') greeting = "Hallo, Willkommen auf meiner Website!"
if (country === 'FR') greeting = "Bonjour, Bienvenue sur mon site !"
if (country === 'JP') greeting = "こんにちは、私のサイトへようこそ！"
// Fetch the original page
let response = await fetch(request)
let html = await response.text()
// Inject the personalized greeting
html = html.replace('', greeting)
// Return the personalized page
return new Response(html, response)
}
// For all other pages, fetch the original request
return fetch(request)
}
In your `index.html` file, you would have a placeholder element like `
`. The Worker replaces this with a localized greeting based on the user's country code. This creates an immediate connection with international visitors and demonstrates a level of polish that sets your site apart. You can extend this concept to show localized events, currency, or language-specific content recommendations.By integrating Cloudflare Workers with your GitHub Pages site, you break free from the limitations of static hosting without sacrificing its benefits. You add a layer of intelligence and dynamism that responds to your users in real-time, creating more engaging and effective experiences. The edge is the new frontier for web development, and Workers are your tool to harness its power.
Adding dynamic features is powerful, but it must be done with search engine visibility in mind. Next, we will explore how to ensure your optimized and dynamic GitHub Pages site remains fully visible and ranks highly in search engine results through advanced SEO techniques.