Start from existing

Workers Sites require Wrangler — make sure to use the latest version.

To deploy a pre-existing static site project, start with a pre-generated site. Workers Sites works with all static site generators, for example:

• Hugo
• Gatsby, requires Node
• Jekyll, requires Ruby
• Eleventy, requires Node
• WordPress (refer to the tutorial on deploying static WordPress sites with Pages)

Getting started

1. Run the wrangler init command in the root of your project's directory to generate a basic Worker:

   wrangler init -y

   This command adds/update the following files:

   • wrangler.jsonc: The file containing project configuration.
   • package.json: Wrangler devDependencies are added.
   • tsconfig.json: Added if not already there to support writing the Worker in TypeScript.
   • src/index.ts: A basic Cloudflare Worker, written in TypeScript.

2. Add your site's build/output directory to the Wrangler file:

   wrangler.jsonc

   wrangler.toml

   {
     "site": {
       "bucket": "./public" // <-- Add your build directory name here.
     }
   }

   [site]
   bucket = "./public"
   

   The default directories for the most popular static site generators are listed below:

   • Hugo: public
   • Gatsby: public
   • Jekyll: _site
   • Eleventy: _site

3. Install the @cloudflare/kv-asset-handler package in your project:

   npm i -D @cloudflare/kv-asset-handler

4. Replace the contents of src/index.ts with the following code snippet:

import { getAssetFromKV } from "@cloudflare/kv-asset-handler";
import manifestJSON from "__STATIC_CONTENT_MANIFEST";
const assetManifest = JSON.parse(manifestJSON);

export default {
	async fetch(request, env, ctx) {
		try {
			// Add logic to decide whether to serve an asset or run your original Worker code
			return await getAssetFromKV(
				{
					request,
					waitUntil: ctx.waitUntil.bind(ctx),
				},
				{
					ASSET_NAMESPACE: env.__STATIC_CONTENT,
					ASSET_MANIFEST: assetManifest,
				},
			);
		} catch (e) {
			let pathname = new URL(request.url).pathname;
			return new Response(`"${pathname}" not found`, {
				status: 404,
				statusText: "not found",
			});
		}
	},
};

import { getAssetFromKV } from "@cloudflare/kv-asset-handler";

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

async function handleEvent(event) {
	try {
		// Add logic to decide whether to serve an asset or run your original Worker code
		return await getAssetFromKV(event);
	} catch (e) {
		let pathname = new URL(event.request.url).pathname;
		return new Response(`"${pathname}" not found`, {
			status: 404,
			statusText: "not found",
		});
	}
}

5. Run wrangler dev or npx wrangler deploy to preview or deploy your site on Cloudflare. Wrangler will automatically upload the assets found in the configured directory.

   npx wrangler deploy

6. Deploy your site to a custom domain that you own and have already attached as a Cloudflare zone. Add a route property to the Wrangler file.

   wrangler.jsonc

   wrangler.toml

   {
     "route": "https://example.com/*"
   }

   route = "https://example.com/*"
   

   Note

   Refer to the documentation on Routes to configure a route properly.

Learn more about configuring your project.