LightweightLightweight
Sign InGet Started
Back to Documentation

Cloudflare

Host your blog on a custom subpath with Cloudflare Workers.

To host your blog at a custom subpath such as yoursite.com/blog using Cloudflare, you will need to create and configure a Cloudflare Worker.

Before you begin, you need a Cloudflare account and a domain name (can be managed on or off Cloudflare).

1. Set up a Cloudflare Worker

Create a Cloudflare Worker by following the Cloudflare Workers getting started guide, if you have not already.

If your DNS provider is Cloudflare, disable proxying for the CNAME record to avoid potential configuration issues.

Configure routing

In your Cloudflare dashboard, select Edit Code and add the following script into your Worker's code. See the Cloudflare documentation for more information on editing a Worker.

Replace [YOUR_SUBDOMAIN] with your unique subdomain, [YOUR_DOMAIN] with your website's base URL, and /blog with your desired subpath if different.

addEventListener("fetch", (event) => {
  event.respondWith(handleRequest(event.request));
});

async function handleRequest(request) {
  try {
    const url = new URL(request.url);
    
    if (url.pathname.startsWith('/.well-known/')) {
      return await fetch(request);
    }
    
    // Replace [SUBDOMAIN] with your subdomain
    const BLOG_URL = "[SUBDOMAIN].lightweight.dev";
    
    // Always proxy /blog
    if (/^/blog/.test(url.pathname)) {  
      const proxyUrl = new URL(request.url);
      proxyUrl.hostname = BLOG_URL;
      
      const proxyRequest = new Request(proxyUrl, request);
      proxyRequest.headers.set("Host", BLOG_URL);
      proxyRequest.headers.set("X-Forwarded-Host", url.hostname);
      proxyRequest.headers.set("X-Forwarded-Proto", "https");
      
      return await fetch(proxyRequest);
    }
    
    // Proxy _next ONLY if from blog
    const referer = request.headers.get('Referer') || '';
    const isFromBlog = referer.includes('/blog');
    
    if (isFromBlog && /^/_next/.test(url.pathname)) {  
      const proxyUrl = new URL(request.url);
      proxyUrl.hostname = BLOG_URL;
      
      const proxyRequest = new Request(proxyUrl, request);
      proxyRequest.headers.set("Host", BLOG_URL);
      proxyRequest.headers.set("X-Forwarded-Host", url.hostname);
      proxyRequest.headers.set("X-Forwarded-Proto", "https");
      
      return await fetch(proxyRequest);
    }
    
    return await fetch(request);
    
  } catch (error) {
    return await fetch(request);
  }
}

Select Deploy and wait for the changes to propagate.

2. Configure Worker Routes

In your Cloudflare dashboard, navigate to your Worker and go to Worker Routes.

  1. Click Add Route
  2. Add the following two routes (replace yourdomain.com with your actual domain):
    • yourdomain.com/blog*(handles all blog pages)
    • yourdomain.com/_next/*(handles Next.js assets)
  3. For each route, select the Worker you just created from the dropdown
  4. Click Save

Why two routes?

  • /blog* proxies your blog content
  • /_next/* proxies Next.js static assets (CSS, JS, images)

After configuring your DNS and Worker routes, custom subdomains are usually available within a few minutes. DNS propagation can sometimes take 1-4 hours, and in rare cases up to 48 hours. If your subdomain is not immediately available, please wait before troubleshooting.

Test your Worker

After your code deploys, test your Worker to ensure it routes to your Lightweight blog.

  1. Test using the Worker's preview URL: your-worker.your-subdomain.workers.dev/blog
  2. Verify the Worker routes to your Lightweight blog and your website.

Add custom domain

  1. In your Cloudflare dashboard, navigate to your Worker.
  2. Go to Settings > Domains & Routes > Add > Custom Domain.
  3. Add your domain.

We recommend you add your domain both with and without www. prepended.

See Add a custom domain in the Cloudflare documentation for more information.

Resolve DNS conflicts

If your domain already points to another service, you must remove the existing DNS record. Your Cloudflare Worker must be configured to control all traffic for your domain.

  1. Delete the existing DNS record for your domain. See Delete DNS records in the Cloudflare documentation for more information.
  2. Return to your Worker and add your custom domain.