Skip to content

Commit d6c23c3

Browse files
Seth Raphaelclaude
Seth Raphael
and
claude
committed
Migrate from Cloudflare Pages to Workers Static Assets
Cloudflare Pages is deprecated; Workers with Static Assets is the official successor for serving static files from Cloudflare's edge. Changes: - Replace upload-cloudflare-pages.ts with upload-cloudflare-workers.ts - Use `wrangler deploy` with temporary wrangler.json instead of `wrangler pages deploy` - Update CLI flags: --cloudflare-pages -> --cloudflare-workers - Update CLI flags: --pages-project -> --worker-name - Update env var: CLOUDFLARE_PAGES_PROJECT -> CLOUDFLARE_WORKER_NAME - Simplify setup wizard (Workers auto-create on deploy) - Update README documentation Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
1 parent 4de3c51 commit d6c23c3

6 files changed

Lines changed: 236 additions & 387 deletions

File tree

‎README.md‎

Lines changed: 29 additions & 31 deletions
Original file line numberDiff line numberDiff line change
@@ -117,8 +117,8 @@ Options:
117117
--dev Deploy to dev deployment (default)
118118
-b, --build Run 'npm run build' with correct VITE_CONVEX_URL
119119
--domain <name> Custom domain for URL output and Cloudflare cache purge
120-
--cloudflare-pages Deploy to Cloudflare Pages instead of Convex storage
121-
--pages-project <name> Cloudflare Pages project name
120+
--cloudflare-workers Deploy to Cloudflare Workers instead of Convex storage
121+
--worker-name <name> Cloudflare Worker name
122122
-h, --help Show help
123123
```
124124

@@ -131,8 +131,8 @@ npx @get-convex/self-static-hosting upload --build --prod
131131
# Deploy to production with custom domain (also purges Cloudflare cache)
132132
npx @get-convex/self-static-hosting upload --build --prod --domain mysite.com
133133

134-
# Deploy to Cloudflare Pages instead
135-
npx @get-convex/self-static-hosting upload --build --prod --cloudflare-pages --pages-project my-app
134+
# Deploy to Cloudflare Workers instead
135+
npx @get-convex/self-static-hosting upload --build --prod --cloudflare-workers --worker-name my-app
136136

137137
# Deploy to dev (for testing)
138138
npx @get-convex/self-static-hosting upload --build
@@ -147,10 +147,10 @@ Deploy both Convex backend and static files with a single command:
147147
```bash
148148
# Make sure you're logged in
149149
npx convex login
150-
npx wrangler login # if using Cloudflare Pages
150+
npx wrangler login # if using Cloudflare Workers
151151

152-
# Deploy everything to Cloudflare Pages
153-
npx @get-convex/self-static-hosting deploy --cloudflare-pages --pages-project my-app
152+
# Deploy everything to Cloudflare Workers
153+
npx @get-convex/self-static-hosting deploy --cloudflare-workers --worker-name my-app
154154

155155
# Or deploy everything to Convex storage
156156
npx @get-convex/self-static-hosting deploy
@@ -159,7 +159,7 @@ npx @get-convex/self-static-hosting deploy
159159
The `deploy` command:
160160
1. Builds frontend with production `VITE_CONVEX_URL`
161161
2. Deploys Convex backend (`npx convex deploy`)
162-
3. Deploys static files (to CF Pages or Convex storage)
162+
3. Deploys static files (to CF Workers or Convex storage)
163163

164164
This minimizes the inconsistency window between backend and frontend updates.
165165

@@ -171,8 +171,8 @@ npx @get-convex/self-static-hosting deploy [options]
171171
Options:
172172
-d, --dist <path> Path to dist directory (default: ./dist)
173173
-c, --component <name> Convex component name (default: staticHosting)
174-
--cloudflare-pages Deploy static files to Cloudflare Pages
175-
--pages-project <name> Cloudflare Pages project name
174+
--cloudflare-workers Deploy static files to Cloudflare Workers
175+
--worker-name <name> Cloudflare Worker name
176176
--skip-build Skip the build step (use existing dist)
177177
--skip-convex Skip Convex backend deployment
178178
-h, --help Show help
@@ -183,7 +183,7 @@ Add to `package.json` for easy deployments:
183183
```json
184184
{
185185
"scripts": {
186-
"deploy": "npx @get-convex/self-static-hosting deploy --cloudflare-pages --pages-project my-app"
186+
"deploy": "npx @get-convex/self-static-hosting deploy --cloudflare-workers --worker-name my-app"
187187
}
188188
}
189189
```
@@ -225,18 +225,19 @@ The upload API uses **internal functions** that can only be called via:
225225
This means unauthorized users **cannot** upload files to your site, even if they
226226
know your Convex URL.
227227

228-
## Cloudflare Pages (Recommended)
228+
## Cloudflare Workers (Recommended)
229229

230-
Deploy your static files directly to Cloudflare Pages for the best performance.
231-
Files are served from Cloudflare's edge network without needing Convex storage.
230+
Deploy your static files directly to Cloudflare Workers with Static Assets for
231+
the best performance. Files are served from Cloudflare's edge network without
232+
needing Convex storage.
232233

233234
### Benefits
234235

235236
- Files served directly from Cloudflare edge (no origin fetch)
236237
- No Convex storage costs for static assets
237-
- No Worker proxy needed
238238
- Built-in SPA routing support
239239
- Automatic SSL/HTTPS
240+
- Workers are created automatically on first deploy
240241

241242
### Quick Setup
242243

@@ -245,15 +246,14 @@ npx @get-convex/self-static-hosting setup-cloudflare
245246
```
246247

247248
The wizard will ask you to choose between:
248-
1. **Cloudflare Pages** (recommended) - Files hosted on CF edge
249+
1. **Cloudflare Workers** (recommended) - Files hosted on CF edge
249250
2. **Convex Storage + Cloudflare CDN** - Files in Convex, cached by CF
250251

251-
For Cloudflare Pages, the wizard will:
252+
For Cloudflare Workers, the wizard will:
252253
1. Login to Cloudflare (via wrangler)
253-
2. Create a Pages project (or use existing)
254-
3. Optionally configure a custom domain
255-
4. Save configuration to `.env.local`
256-
5. Offer to build and deploy
254+
2. Configure a worker name
255+
3. Save configuration to `.env.local`
256+
4. Offer to build and deploy
257257

258258
### Manual Setup
259259

@@ -262,44 +262,42 @@ For Cloudflare Pages, the wizard will:
262262
npx wrangler login
263263
```
264264

265-
2. Deploy to Cloudflare Pages:
265+
2. Deploy to Cloudflare Workers:
266266
```bash
267267
npx @get-convex/self-static-hosting upload --build --prod \
268-
--cloudflare-pages --pages-project my-app
268+
--cloudflare-workers --worker-name my-app
269269
```
270270

271271
3. Add to `package.json`:
272272
```json
273273
{
274274
"scripts": {
275-
"deploy:static": "npx @get-convex/self-static-hosting upload --build --prod --cloudflare-pages"
275+
"deploy:static": "npx @get-convex/self-static-hosting upload --build --prod --cloudflare-workers"
276276
}
277277
}
278278
```
279279

280-
4. Set environment variable (optional, alternative to `--pages-project`):
280+
4. Set environment variable (optional, alternative to `--worker-name`):
281281
```bash
282-
export CLOUDFLARE_PAGES_PROJECT=my-app
282+
export CLOUDFLARE_WORKER_NAME=my-app
283283
```
284284

285285
### Custom Domains
286286

287287
Add custom domains in the Cloudflare dashboard:
288-
- Go to Workers & Pages → your project → Custom domains → Add
289-
290-
Or use the setup wizard which can configure this for you.
288+
- Go to Workers & Pages → your worker → Settings → Triggers → Custom Domains
291289

292290
### Live Reload
293291

294-
The live reload feature still works with Cloudflare Pages! The CLI updates
292+
The live reload feature still works with Cloudflare Workers! The CLI updates
295293
Convex deployment info after each deploy, so connected clients get notified.
296294

297295
---
298296

299297
## CDN Setup (Convex Storage + Cloudflare)
300298

301299
If you prefer to keep static files in Convex storage (instead of Cloudflare
302-
Pages), you can put Cloudflare in front as a CDN for edge caching, compression,
300+
Workers), you can put Cloudflare in front as a CDN for edge caching, compression,
303301
DDoS protection, and custom domains.
304302

305303
### Quick Setup

‎src/cli/deploy.ts‎

Lines changed: 32 additions & 32 deletions
Original file line numberDiff line numberDiff line change
@@ -8,22 +8,22 @@
88
* This command:
99
* 1. Builds the frontend with the correct VITE_CONVEX_URL
1010
* 2. Deploys the Convex backend (npx convex deploy)
11-
* 3. Deploys static files to Cloudflare Pages or Convex storage
11+
* 3. Deploys static files to Cloudflare Workers or Convex storage
1212
*
1313
* The goal is to minimize the inconsistency window between backend and frontend.
1414
*/
1515

1616
import { existsSync, readFileSync } from "fs";
1717
import { resolve } from "path";
1818
import { execSync, spawnSync } from "child_process";
19-
import { deployToCloudflarePages } from "./upload-cloudflare-pages.js";
19+
import { deployToCloudflareWorkers } from "./upload-cloudflare-workers.js";
2020

2121
interface ParsedArgs {
2222
dist: string;
2323
component: string;
2424
help: boolean;
25-
cloudflarePages: boolean;
26-
pagesProject: string | null;
25+
cloudflareWorkers: boolean;
26+
workerName: string | null;
2727
skipBuild: boolean;
2828
skipConvex: boolean;
2929
}
@@ -33,8 +33,8 @@ function parseArgs(args: string[]): ParsedArgs {
3333
dist: "./dist",
3434
component: "staticHosting",
3535
help: false,
36-
cloudflarePages: false,
37-
pagesProject: null,
36+
cloudflareWorkers: false,
37+
workerName: null,
3838
skipBuild: false,
3939
skipConvex: false,
4040
};
@@ -47,10 +47,10 @@ function parseArgs(args: string[]): ParsedArgs {
4747
result.dist = args[++i] || result.dist;
4848
} else if (arg === "--component" || arg === "-c") {
4949
result.component = args[++i] || result.component;
50-
} else if (arg === "--cloudflare-pages") {
51-
result.cloudflarePages = true;
52-
} else if (arg === "--pages-project") {
53-
result.pagesProject = args[++i] || null;
50+
} else if (arg === "--cloudflare-workers") {
51+
result.cloudflareWorkers = true;
52+
} else if (arg === "--worker-name") {
53+
result.workerName = args[++i] || null;
5454
} else if (arg === "--skip-build") {
5555
result.skipBuild = true;
5656
} else if (arg === "--skip-convex") {
@@ -59,9 +59,9 @@ function parseArgs(args: string[]): ParsedArgs {
5959
}
6060

6161
// Check environment variables
62-
if (!result.pagesProject && process.env.CLOUDFLARE_PAGES_PROJECT) {
63-
result.pagesProject = process.env.CLOUDFLARE_PAGES_PROJECT;
64-
result.cloudflarePages = true;
62+
if (!result.workerName && process.env.CLOUDFLARE_WORKER_NAME) {
63+
result.workerName = process.env.CLOUDFLARE_WORKER_NAME;
64+
result.cloudflareWorkers = true;
6565
}
6666

6767
return result;
@@ -77,32 +77,32 @@ Minimizes the inconsistency window between backend and frontend updates.
7777
Options:
7878
-d, --dist <path> Path to dist directory (default: ./dist)
7979
-c, --component <name> Convex component name (default: staticHosting)
80-
--cloudflare-pages Deploy static files to Cloudflare Pages
81-
--pages-project <name> Cloudflare Pages project name
80+
--cloudflare-workers Deploy static files to Cloudflare Workers (Static Assets)
81+
--worker-name <name> Worker name for deployment
8282
--skip-build Skip the build step (use existing dist)
8383
--skip-convex Skip Convex backend deployment
8484
-h, --help Show this help message
8585
8686
Environment Variables:
87-
CLOUDFLARE_PAGES_PROJECT Default Pages project name (enables --cloudflare-pages)
87+
CLOUDFLARE_WORKER_NAME Default worker name (enables --cloudflare-workers)
8888
8989
Deployment Flow:
9090
1. Build frontend with production VITE_CONVEX_URL
9191
2. Deploy Convex backend (npx convex deploy)
92-
3. Deploy static files to CF Pages or Convex storage
92+
3. Deploy static files to CF Workers or Convex storage
9393
9494
Examples:
95-
# Full deployment to Cloudflare Pages
96-
npx @get-convex/self-static-hosting deploy --cloudflare-pages --pages-project my-app
95+
# Full deployment to Cloudflare Workers
96+
npx @get-convex/self-static-hosting deploy --cloudflare-workers --worker-name my-app
9797
9898
# Full deployment to Convex storage
9999
npx @get-convex/self-static-hosting deploy
100100
101101
# Skip build (if already built)
102-
npx @get-convex/self-static-hosting deploy --skip-build --cloudflare-pages
102+
npx @get-convex/self-static-hosting deploy --skip-build --cloudflare-workers
103103
104104
# Only deploy static files (skip Convex backend)
105-
npx @get-convex/self-static-hosting deploy --skip-convex --cloudflare-pages
105+
npx @get-convex/self-static-hosting deploy --skip-convex --cloudflare-workers
106106
`);
107107
}
108108

@@ -290,33 +290,33 @@ async function main(): Promise<void> {
290290

291291
let staticDeploySuccess = false;
292292

293-
if (args.cloudflarePages) {
294-
if (!args.pagesProject) {
293+
if (args.cloudflareWorkers) {
294+
if (!args.workerName) {
295295
console.error("");
296-
console.error("❌ --pages-project is required when using --cloudflare-pages");
297-
console.error(" Or set CLOUDFLARE_PAGES_PROJECT environment variable");
296+
console.error("--worker-name is required when using --cloudflare-workers");
297+
console.error(" Or set CLOUDFLARE_WORKER_NAME environment variable");
298298
process.exit(1);
299299
}
300300

301-
console.log(` Target: Cloudflare Pages (${args.pagesProject})`);
301+
console.log(` Target: Cloudflare Workers (${args.workerName})`);
302302
console.log("");
303303

304-
const result = await deployToCloudflarePages({
304+
const result = await deployToCloudflareWorkers({
305305
distDir,
306-
projectName: args.pagesProject,
306+
workerName: args.workerName,
307307
convexComponent: args.component,
308308
prod: true,
309309
});
310310

311311
if (!result.success) {
312312
console.error("");
313-
console.error(`❌ ${result.error}`);
313+
console.error(`${result.error}`);
314314
process.exit(1);
315315
}
316316

317317
staticDeploySuccess = true;
318318
console.log("");
319-
console.log(` ✓ Deployed to ${result.url}`);
319+
console.log(` Deployed to ${result.url}`);
320320
} else {
321321
console.log(" Target: Convex storage");
322322
staticDeploySuccess = await uploadToConvexStorage(distDir, args.component);
@@ -337,8 +337,8 @@ async function main(): Promise<void> {
337337
console.log("");
338338

339339
// Show URLs
340-
if (args.cloudflarePages && args.pagesProject) {
341-
console.log(`Frontend: https://${args.pagesProject}.pages.dev`);
340+
if (args.cloudflareWorkers && args.workerName) {
341+
console.log(`Frontend: https://${args.workerName}.workers.dev`);
342342
} else {
343343
// Get Convex site URL
344344
try {

‎src/cli/index.ts‎

Lines changed: 9 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -4,8 +4,8 @@
44
*
55
* Commands:
66
* deploy One-shot deployment (Convex backend + static files)
7-
* upload Upload static files to Convex or Cloudflare Pages
8-
* setup-cloudflare Interactive Cloudflare CDN setup
7+
* upload Upload static files to Convex or Cloudflare Workers
8+
* setup-cloudflare Interactive Cloudflare setup wizard
99
* init Print setup instructions
1010
*/
1111

@@ -58,13 +58,13 @@ Usage:
5858
5959
Commands:
6060
deploy One-shot deployment (Convex backend + static files)
61-
upload Upload static files to Convex storage or Cloudflare Pages
61+
upload Upload static files to Convex storage or Cloudflare Workers
6262
setup-cloudflare Interactive Cloudflare setup wizard
6363
init Print setup instructions for integration
6464
6565
Examples:
66-
# One-shot deployment to Cloudflare Pages
67-
npx @get-convex/self-static-hosting deploy --cloudflare-pages --pages-project my-app
66+
# One-shot deployment to Cloudflare Workers
67+
npx @get-convex/self-static-hosting deploy --cloudflare-workers --worker-name my-app
6868
6969
# One-shot deployment to Convex storage
7070
npx @get-convex/self-static-hosting deploy
@@ -112,7 +112,7 @@ import { components } from "./_generated/api";
112112
113113
const http = httpRouter();
114114
115-
// Serve static files (skip this if using Cloudflare Pages)
115+
// Serve static files (skip this if using Cloudflare Workers)
116116
registerStaticRoutes(http, components.selfStaticHosting, {
117117
pathPrefix: "/", // or "/app" to keep API routes separate
118118
spaFallback: true,
@@ -143,7 +143,7 @@ export const { getCurrentDeployment } =
143143
{
144144
"scripts": {
145145
"build": "vite build",
146-
"deploy": "npx @get-convex/self-static-hosting deploy --cloudflare-pages --pages-project my-app"
146+
"deploy": "npx @get-convex/self-static-hosting deploy --cloudflare-workers --worker-name my-app"
147147
}
148148
}
149149
\`\`\`
@@ -163,7 +163,7 @@ Or for Convex storage mode:
163163
\`\`\`bash
164164
# Login first
165165
npx convex login
166-
npx wrangler login # if using Cloudflare Pages
166+
npx wrangler login # if using Cloudflare Workers
167167
168168
# One-shot deployment (backend + static files)
169169
npm run deploy
@@ -177,7 +177,7 @@ npx @get-convex/self-static-hosting setup-cloudflare
177177
178178
This interactive wizard will help you choose between:
179179
180-
1. **Cloudflare Pages** (recommended)
180+
1. **Cloudflare Workers** (recommended)
181181
- Files served directly from Cloudflare edge
182182
- No Convex storage costs for static assets
183183
- Built-in SPA routing

0 commit comments

Comments
 (0)