Hosting a Static Website with Cloudflare Worker

Aiko · March 18, 2025, 2:44pm

Key Points

Research suggests Cloudflare Workers can host static websites by serving assets directly, but it’s more complex than using Cloudflare Pages, which is designed for static sites.
The evidence leans toward using Cloudflare Workers for static sites requiring custom logic, while Cloudflare Pages is simpler for traditional static hosting.
It seems likely that for a basic static website, you’ll need to set up Wrangler CLI, configure an assets directory, and deploy, with optional Worker code for advanced routing.

Direct Answer

To host a static website with Cloudflare Workers, start by signing up for a Cloudflare account at cloudflare.com. Install the Wrangler CLI using npm install -g wrangler or pnpm install wrangler. Create a project directory, add your static files (like HTML, CSS, and images) to a folder (e.g., “public”), and configure a wrangler.toml file to point to this folder. Deploy your site with wrangler deploy, and access it at a URL like https://your-worker-name.yourusername.workers.dev/.

For clean URLs or single-page apps, you might need to add basic Worker code to handle routing, which can be unexpected for users expecting a simpler setup. Cloudflare Pages is often easier for static sites, but Workers offer flexibility for custom logic, which might be useful if you plan to add dynamic features later.

Survey Note: Detailed Analysis of Hosting a Static Website with Cloudflare Workers

This analysis explores how to host a static website using Cloudflare Workers, a platform primarily designed for running JavaScript code at the edge, but also capable of serving static assets. Given the current time is 07:26 AM PDT on Tuesday, March 18, 2025, all information is aligned with recent developments. The goal is to provide a comprehensive guide for users, considering both the official documentation and community insights, while acknowledging the complexity compared to alternatives like Cloudflare Pages.

Overview of Hosting Static Websites with Cloudflare Workers

Hosting a static website typically involves serving HTML, CSS, JavaScript, and other assets without server-side processing. Cloudflare Workers, known for edge computing, can also host static assets through its infrastructure, offering global distribution and low latency. This is distinct from Cloudflare Pages, which is specifically tailored for static site hosting with Git integration. The process involves using the Wrangler CLI to deploy assets and optionally handle requests with Worker code, which may add complexity for users expecting a simpler setup.

Step-by-Step Guide for Hosting with Cloudflare Workers

To host a static website with Cloudflare Workers, follow these detailed steps:

Set Up a Cloudflare Account:
- Visit cloudflare.com and sign up for an account. This is necessary to access Workers and manage deployments.
Install Wrangler CLI:
- Wrangler is the command-line tool for deploying Cloudflare Workers. Install it using Node.js package manager with npm install -g wrangler or pnpm install wrangler. Ensure you have Node.js installed on your system.
Create a Project Directory:
- Create a new directory for your project, e.g., my-static-site, using mkdir my-static-site and navigate into it with cd my-static-site.
Prepare Static Files:
- Create a directory for your static assets, typically named “public” by convention, though you can name it anything (e.g., “assets” or “content”). Place all your static files (index.html, styles.css, images, etc.) in this directory. For example, to serve https://example.com/index.html, ensure index.html is in the root of this directory.
Configure wrangler.toml:
- Create a wrangler.toml file in your project directory with the following content:
```
name = "my-static-site"
compatibility_date = "2024-09-25"
assets = {
  directory = "public"
}
```
- Replace "my-static-site" with your desired Worker name. The compatibility_date ensures compatibility with recent Workers features, and the assets section points to your static files directory.
Optional: Add Worker Code for Advanced Routing:
- By default, if a requested URL matches a file in the assets directory, it is served directly without running Worker code. However, for requests that don’t match (e.g., /about with no about.html), the Worker code is executed. For a traditional static website with separate HTML files, ensure all pages are present. For single-page applications (SPAs) or clean URLs, create a worker.js file with code like:
```
export default {
  async fetch(request) {
    const url = new URL(request.url);
    const file = await env.ASSETS.fetch(request);
    return file;
  },
};
```
- This ensures assets are served, but you may need additional logic for 404 handling or serving index.html for SPA routing.
Deploy the Worker:
- Run wrangler deploy in your terminal. This uploads your static assets and any Worker code to Cloudflare’s infrastructure, deploying your site across their global network.
Access Your Site:
- After deployment, your site will be accessible at a URL like https://my-static-site.yourusername.workers.dev/, where yourusername is your Cloudflare account username. Test by visiting this URL in a browser.
Optional: Set Up Custom Domain:
- To use a custom domain (e.g., www.example.com), follow Cloudflare’s documentation for adding a custom domain to Workers. This involves adding a DNS record (CNAME) pointing to your Worker’s subdomain and configuring it in the Cloudflare dashboard.

Comparative Analysis with Cloudflare Pages

While Cloudflare Workers can host static websites, Cloudflare Pages is specifically designed for this purpose, offering Git integration and automatic builds. The following table compares the two for hosting static websites:

Feature	Cloudflare Workers	Cloudflare Pages
Primary Use Case	Edge computing, dynamic logic	Static site hosting, JAMstack
Git Integration	No (manual deployment with Wrangler)	Yes (automatic builds from GitHub/GitLab)
Ease of Use for Static Sites	More complex, requires CLI setup	Simpler, GUI-based with build settings
Custom Logic	Yes, can mix static assets with code	Limited, mainly for static assets
Free Tier	Yes, with usage limits	Yes, with 500 builds/month, unlimited bandwidth
Asset Serving	Direct for matching URLs, Worker code for others	Direct, with build process handling

Considerations and Unexpected Details

An unexpected detail is that while Cloudflare Pages is often recommended for static sites due to its simplicity, using Workers allows for mixing static assets with dynamic functionality, such as WebSockets or Durable Objects, which Pages cannot handle. This flexibility might appeal to users planning future enhancements, but it adds complexity for basic static hosting. Additionally, the need for Wrangler CLI and potential Worker code for routing might surprise users expecting a plug-and-play solution like Pages.

Conclusion and Recommendation

Research suggests that hosting a static website with Cloudflare Workers is viable, especially for users comfortable with CLI tools and needing custom logic. The evidence leans toward using Workers for scenarios where dynamic features are anticipated, while Cloudflare Pages is better for traditional static site hosting. For a basic static website, follow the steps above, ensuring all pages are covered by assets in the directory. For advanced routing, consider adding Worker code, acknowledging the added complexity compared to Pages.