cloudflare-worker-base

Name: cloudflare-worker-base
Author: jackspace

15stars7forks

How to install cloudflare-worker-base?

jackspace/claudeskillz/cloudflare-worker-base

$npx -y skills add jackspace/ClaudeSkillz --skill cloudflare-worker-base

Installs into the current project.

Summary

Production-tested setup for Cloudflare Workers with Hono, Vite, and Static Assets. Use when: creating new Cloudflare Workers projects, setting up Hono routing with Workers, configuring Vite plugin for Workers, adding Static Assets to Workers, deploying with Wrangler, or encounter

Files · 1

View on GitHub

SKILL.md

1	# Cloudflare Worker Base Stack
2
3	Production-tested: cloudflare-worker-base-test (https://cloudflare-worker-base-test.webfonts.workers.dev)
4	Last Updated: 2025-10-20
5	Status: Production Ready ✅
6
7	---
8
9	## Quick Start (5 Minutes)
10
11	### 1. Scaffold Project
12
13	```bash
14	npm create cloudflare@latest my-worker -- \
15	--type hello-world \
16	--ts \
17	--git \
18	--deploy false \
19	--framework none
20	```
21
22	Why these flags:
23	- `--type hello-world`: Clean starting point
24	- `--ts`: TypeScript support
25	- `--git`: Initialize git repo
26	- `--deploy false`: Don't deploy yet (configure first)
27	- `--framework none`: We'll add Vite ourselves
28
29	### 2. Install Dependencies
30
31	```bash
32	cd my-worker
33	npm install hono@4.10.1
34	npm install -D @cloudflare/vite-plugin@1.13.13 vite@latest
35	```
36
37	Version Notes:
38	- `hono@4.10.1`: Latest stable (verified 2025-10-20)
39	- `@cloudflare/vite-plugin@1.13.13`: Latest stable, fixes HMR race condition
40	- `vite`: Latest version compatible with Cloudflare plugin
41
42	### 3. Configure Wrangler
43
44	Create or update `wrangler.jsonc`:
45
46	```jsonc
47	{
48	"$schema": "node_modules/wrangler/config-schema.json",
49	"name": "my-worker",
50	"main": "src/index.ts",
51	"account_id": "YOUR_ACCOUNT_ID",
52	"compatibility_date": "2025-10-11",
53	"observability": {
54	"enabled": true
55	},
56	"assets": {
57	"directory": "./public/",
58	"binding": "ASSETS",
59	"not_found_handling": "single-page-application",
60	"run_worker_first": ["/api/*"]
61	}
62	}
63	```
64
65	CRITICAL: `run_worker_first` Configuration
66	- Without this, SPA fallback intercepts API routes
67	- API routes return `index.html` instead of JSON
68	- Source: [workers-sdk #8879](https://github.com/cloudflare/workers-sdk/issues/8879)
69
70	### 4. Configure Vite
71
72	Create `vite.config.ts`:
73
74	```typescript
75	import { defineConfig } from 'vite'
76	import { cloudflare } from '@cloudflare/vite-plugin'
77
78	export default defineConfig({
79	plugins: [
80	cloudflare({
81	// Optional: Configure the plugin if needed
82	}),
83	],
84	})
85	```
86
87	Why @cloudflare/vite-plugin:
88	- Official plugin from Cloudflare
89	- Supports HMR with Workers
90	- Enables local development with Miniflare
91	- Version 1.13.13 fixes "A hanging Promise was canceled" error
92
93	---
94
95	## The Four-Step Setup Process
96
97	### Step 1: Create Hono App with API Routes
98
99	Create `src/index.ts`:
100
101	```typescript
102	/**
103	* Cloudflare Worker with Hono
104	*
105	* CRITICAL: Export pattern to prevent build errors
106	* ✅ CORRECT: export default app
107	* ❌ WRONG: export default { fetch: app.fetch }
108	*/
109
110	import { Hono } from 'hono'
111
112	// Type-safe environment bindings
113	type Bindings = {
114	ASSETS: Fetcher
115	}
116
117	const app = new Hono<{ Bindings: Bindings }>()
118
119	/**
120	* API Routes
121	* Handled BEFORE static assets due to run_worker_first config
122	*/
123	app.get('/api/hello', (c) => {
124	return c.json({
125	message: 'Hello from Cloudflare Workers!',
126	timestamp: new Date().toISOString(),
127	})
128	})
129
130	app.get('/api/health', (c) => {
131	return c.json({
132	status: 'ok',
133	version: '1.0.0',
134	environment: c.env ? 'production' : 'development',
135	})
136	})
137
138	/**
139	* Fallback to Static Assets
140	* Any route not matched above is served from public/ directory
141	*/
142	app.all('*', (c) => {
143	return c.env.ASSETS.fetch(c.req.raw)
144	})
145
146	/**
147	* Export the Hono app directly (ES Module format)
148	* This is the correct pattern for Cloudflare Workers with Hono + Vite
149	*/
150	export default app
151	```
152
153	Why This Export Pattern:
154	- Source: [honojs/hono #3955](https://github.com/honojs/hono/issues/3955)
155	- Using `{ fetch: app.fetch }` causes: "Cannot read properties of undefined (reading 'map')"
156	- Exception: If you need scheduled/tail handlers, use Module Worker format:
157	```typescript
158	export default {
159	fetch: app.fetch,
160	scheduled: async (event, env, ctx) => { /* ... */ }
161	}
162	```
163
164	### Step 2: Create Static Frontend
165
166	Create `public/index.html`:
167
168	```html
169	<!DOCTYPE html>
170	<html lang="en">
171	<head>
172	<meta charset="UTF-8">
173	<meta name="viewport" content="width=device-width, initial-scale=1.0">
174	<title>My Worker App</title>
175	<link rel="stylesheet" href="/styles.css">
176	</head>

People who liked this also viewed

6 picks

Type

cloudflare-worker-base

15stars7forks

View on GitHub

How to install cloudflare-worker-base?

jackspace/claudeskillz/cloudflare-worker-base

$npx -y skills add jackspace/ClaudeSkillz --skill cloudflare-worker-base

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# Cloudflare Worker Base Stack
2
3	Production-tested: cloudflare-worker-base-test (https://cloudflare-worker-base-test.webfonts.workers.dev)
4	Last Updated: 2025-10-20
5	Status: Production Ready ✅
6
7	---
8
9	## Quick Start (5 Minutes)
10
11	### 1. Scaffold Project
12
13	```bash
14	npm create cloudflare@latest my-worker -- \
15	--type hello-world \
16	--ts \
17	--git \
18	--deploy false \
19	--framework none
20	```
21
22	Why these flags:
23	- `--type hello-world`: Clean starting point
24	- `--ts`: TypeScript support
25	- `--git`: Initialize git repo
26	- `--deploy false`: Don't deploy yet (configure first)
27	- `--framework none`: We'll add Vite ourselves
28
29	### 2. Install Dependencies
30
31	```bash
32	cd my-worker
33	npm install hono@4.10.1
34	npm install -D @cloudflare/vite-plugin@1.13.13 vite@latest
35	```
36
37	Version Notes:
38	- `hono@4.10.1`: Latest stable (verified 2025-10-20)
39	- `@cloudflare/vite-plugin@1.13.13`: Latest stable, fixes HMR race condition
40	- `vite`: Latest version compatible with Cloudflare plugin
41
42	### 3. Configure Wrangler
43
44	Create or update `wrangler.jsonc`:
45
46	```jsonc
47	{
48	"$schema": "node_modules/wrangler/config-schema.json",
49	"name": "my-worker",
50	"main": "src/index.ts",
51	"account_id": "YOUR_ACCOUNT_ID",
52	"compatibility_date": "2025-10-11",
53	"observability": {
54	"enabled": true
55	},
56	"assets": {
57	"directory": "./public/",
58	"binding": "ASSETS",
59	"not_found_handling": "single-page-application",
60	"run_worker_first": ["/api/*"]
61	}
62	}
63	```
64
65	CRITICAL: `run_worker_first` Configuration
66	- Without this, SPA fallback intercepts API routes
67	- API routes return `index.html` instead of JSON
68	- Source: [workers-sdk #8879](https://github.com/cloudflare/workers-sdk/issues/8879)
69
70	### 4. Configure Vite
71
72	Create `vite.config.ts`:
73
74	```typescript
75	import { defineConfig } from 'vite'
76	import { cloudflare } from '@cloudflare/vite-plugin'
77
78	export default defineConfig({
79	plugins: [
80	cloudflare({
81	// Optional: Configure the plugin if needed
82	}),
83	],
84	})
85	```
86
87	Why @cloudflare/vite-plugin:
88	- Official plugin from Cloudflare
89	- Supports HMR with Workers
90	- Enables local development with Miniflare
91	- Version 1.13.13 fixes "A hanging Promise was canceled" error
92
93	---
94
95	## The Four-Step Setup Process
96
97	### Step 1: Create Hono App with API Routes
98
99	Create `src/index.ts`:
100
101	```typescript
102	/**
103	* Cloudflare Worker with Hono
104	*
105	* CRITICAL: Export pattern to prevent build errors
106	* ✅ CORRECT: export default app
107	* ❌ WRONG: export default { fetch: app.fetch }
108	*/
109
110	import { Hono } from 'hono'
111
112	// Type-safe environment bindings
113	type Bindings = {
114	ASSETS: Fetcher
115	}
116
117	const app = new Hono<{ Bindings: Bindings }>()
118
119	/**
120	* API Routes
121	* Handled BEFORE static assets due to run_worker_first config
122	*/
123	app.get('/api/hello', (c) => {
124	return c.json({
125	message: 'Hello from Cloudflare Workers!',
126	timestamp: new Date().toISOString(),
127	})
128	})
129
130	app.get('/api/health', (c) => {
131	return c.json({
132	status: 'ok',
133	version: '1.0.0',
134	environment: c.env ? 'production' : 'development',
135	})
136	})
137
138	/**
139	* Fallback to Static Assets
140	* Any route not matched above is served from public/ directory
141	*/
142	app.all('*', (c) => {
143	return c.env.ASSETS.fetch(c.req.raw)
144	})
145
146	/**
147	* Export the Hono app directly (ES Module format)
148	* This is the correct pattern for Cloudflare Workers with Hono + Vite
149	*/
150	export default app
151	```
152
153	Why This Export Pattern:
154	- Source: [honojs/hono #3955](https://github.com/honojs/hono/issues/3955)
155	- Using `{ fetch: app.fetch }` causes: "Cannot read properties of undefined (reading 'map')"
156	- Exception: If you need scheduled/tail handlers, use Module Worker format:
157	```typescript
158	export default {
159	fetch: app.fetch,
160	scheduled: async (event, env, ctx) => { /* ... */ }
161	}
162	```
163
164	### Step 2: Create Static Frontend
165
166	Create `public/index.html`:
167
168	```html
169	<!DOCTYPE html>
170	<html lang="en">
171	<head>
172	<meta charset="UTF-8">
173	<meta name="viewport" content="width=device-width, initial-scale=1.0">
174	<title>My Worker App</title>
175	<link rel="stylesheet" href="/styles.css">
176	</head>

People who liked this also viewed

6 picks

Type