templates

Templates for Cloudflare Workers

Cloudflare Workers let you deploy serverless code instantly across the globe for exceptional performance, reliability, and scale. This repository contains a collection of starter templates for building full-stack applications on Workers. You are encouraged to use, modify, and extend this code!

Getting Started

There are two ways to start building with a template in this repository: the Cloudflare dashboard and C3 (the create-cloudflare CLI).

Starting from the Dashboard

After logging in or signing up through the Cloudflare dashboard, open the Workers templates page and select a template to get started with. From here, you can create a repository and deploy your first Worker without needing a local development environment.

Starting via CLI

To get started locally, run one of the following commands:

npm create cloudflare@latest
# or
pnpm create cloudflare@latest
# or
yarn create cloudflare@latest

For more information on getting started with our CLI, check out the getting started guide.

Additional Resources

Questions about Workers? Join the official Cloudflare Discord or check out the Workers docs!

End-to-End Testing

This repository includes a comprehensive Playwright-based E2E test suite that validates all templates to ensure they work correctly. The test system supports both local development mode (spinning up dev servers) and live mode (testing against deployed templates).

Running E2E Tests

Local Development Mode (Default)

By default, tests run against locally started development servers:

# Run all E2E tests
pnpm run test:e2e

# Run tests for specific templates
pnpm run test:e2e astro-blog-starter-template.spec.ts
pnpm run test:e2e saas-admin-template.spec.ts

# Run tests with UI mode for debugging
pnpm run test:e2e --ui

In local mode:

• Tests start development servers automatically for each template
• Servers use dynamically allocated ports, so existing local services do not conflict
• Uses one worker to keep resource usage predictable
• Servers and temporary environment files are cleaned up between template tests
• Server logs are attached to failed Playwright tests

Live Mode (Testing Deployed Templates)

To test against live deployed templates, set the PLAYWRIGHT_USE_LIVE environment variable:

# Run tests against live deployed templates
pnpm run test:e2e:live

# Run specific template tests in live mode
pnpm run test:e2e:live saas-admin-template.spec.ts

In live mode:

• Tests run against https://{template-name}.templates.workers.dev
• Enables parallel execution (up to 4 workers locally, 2 in CI)
• Faster execution since no local server startup required
• Shorter timeouts since templates are already running

Test Architecture

The test system includes:

• Automatic template discovery: Finds all *-template directories with a dev script
• Collision-free server management: Allocates HTTP and inspector ports dynamically
• Reliable cleanup: Terminates process trees and removes environment files created by the harness
• Actionable failures: Detects early process exits and attaches captured server logs
• Coverage enforcement: Fails when a dev-enabled template has no corresponding E2E spec
• Flexible URL resolution: Automatically determines live URLs from Wrangler configuration

Writing Template Tests

Template tests should be named {template-name}.spec.ts and placed in the playwright-tests/ directory:

import { test, expect } from "./fixtures";

test.describe("My Template", () => {
	test("should render correctly", async ({ page, templateUrl }) => {
		await page.goto(templateUrl);
		await expect(page.getByRole("heading", { name: "Welcome" })).toBeVisible();
	});
});

The templateUrl fixture automatically provides the correct URL (local dev server or live deployment) based on the test mode.

If a template's normal dev command requires remote resources, add an e2e:dev package script backed by local test configuration. The harness prefers e2e:dev when present. Keep mocks at external binding boundaries so the production request handler still runs end to end.

Playwright Codegen

Playwright includes a test code generation utility that records your actions in a chromium browswer. To start the codegen utility run

pnpm playwright codgen

Contributing

We welcome template contributions! If there's a Workers template you think would be valuable, please read our contributing guide and open an issue or pull request.