Skip to content

Commit 016c1d1

Browse files
nevikashahsdnts
nevikashah
authored and
sdnts
committed
add prompt to migrate to workers (cloudflare#22952)
* add prompt to migrate to workers * updating wording
1 parent 940788f commit 016c1d1

File tree

2 files changed

+187
-1
lines changed

2 files changed

+187
-1
lines changed

‎public/workers/prompts/pages-to-workers.txt‎

Lines changed: 176 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,176 @@
1+
Migrate Cloudflare Pages to Workers using the guide below:
2+
3+
# Cloudflare Pages to Workers Migration Guide
4+
5+
## Goal
6+
7+
Migrate a Cloudflare Pages project to Cloudflare Workers with static assets support.
8+
9+
## Core Migration Concepts
10+
11+
### Understanding the Migration
12+
13+
When migrating from Pages to Workers, you're essentially:
14+
15+
1. Moving from Pages deployment commands to Workers deployment commands
16+
2. Converting Pages-specific configuration to Workers format
17+
3. Handling static assets using Workers Assets (not the deprecated Workers Sites)
18+
4. Converting any Pages Functions to Workers format if they exist
19+
20+
### Key Principles
21+
22+
- **Deployment**: Use `wrangler deploy`, never `wrangler pages deploy`
23+
- **Configuration**: Prefer wrangler.jsonc for better documentation support
24+
- **Assets**: Use the modern Workers Assets format: `"assets": {"directory": "path"}`
25+
- **Flexibility**: Adapt the migration to your specific project structure
26+
- **Package Manager**: Use the appropriate package manager for the project (check for bun.lock, bun.lockb, pnpm-lock.yaml, yarn.lock, or package-lock.json)
27+
28+
## Migration Steps
29+
30+
### 1. Prerequisites
31+
32+
- Update Wrangler to version 4 or later using your package manager:
33+
- npm: `npm install --save-dev wrangler@^4.0.0`
34+
- pnpm: `pnpm add --save-dev wrangler@^4.0.0`
35+
- yarn: `yarn add --dev wrangler@^4.0.0`
36+
- bun: `bun add --dev wrangler@^4.0.0`
37+
- This is required as Workers deployment commands have evolved significantly in v4
38+
- Check current version with `npx wrangler --version`
39+
- Install project dependencies if not already installed
40+
- Consult the official Cloudflare documentation for the latest guidance
41+
42+
### 2. Configuration Migration
43+
44+
#### Update Wrangler Configuration
45+
46+
- Convert to wrangler.jsonc format if using .toml or .json
47+
- Replace `pages_build_output_dir` with `"assets": {"directory": "path"}`
48+
- Ensure a `compatibility_date` field exists
49+
50+
#### Example Structure
51+
52+
```jsonc
53+
{
54+
"name": "project-name",
55+
"compatibility_date": "2025-06-05",
56+
"assets": { "directory": "./dist" },
57+
// Add other fields as needed
58+
}
59+
```
60+
61+
### 3. Determine Project Type
62+
63+
**First, check for Pages Functions:**
64+
65+
- Look for a `functions/` directory with .js/.ts files
66+
- If found, you **must** add `wrangler pages functions build` to your build process (see step 6)
67+
68+
**Then, run your build command and check the output directory:**
69+
70+
- **If \_worker.js exists**: You have a Workers script project
71+
- Add `"main": "./path/to/_worker.js"`
72+
- Add binding to assets: `"assets": {"directory": "path", "binding": "ASSETS"}`
73+
- **If no \_worker.js**: You have an assets-only project
74+
- Just use `"assets": {"directory": "path"}` without main field
75+
76+
### 4. Handle \_worker.js (if present)
77+
78+
If your build creates a \_worker.js file or directory:
79+
80+
1. Create a `.assetsignore` file containing `_worker.js`
81+
2. Update your build script to copy it to the output directory
82+
3. This prevents the worker code from being served as a static asset
83+
84+
### 5. Update Package.json Scripts
85+
86+
First, ensure wrangler is updated to v4+ using your package manager:
87+
88+
```bash
89+
# npm
90+
npm install --save-dev wrangler@^4.0.0
91+
# pnpm
92+
pnpm add --save-dev wrangler@^4.0.0
93+
# yarn
94+
yarn add --dev wrangler@^4.0.0
95+
# bun
96+
bun add --dev wrangler@^4.0.0
97+
```
98+
99+
Then replace Pages commands with Workers equivalents:
100+
101+
- `wrangler pages deploy` → `wrangler deploy`
102+
- `wrangler pages dev` → `wrangler dev`
103+
104+
Keep framework-specific commands unchanged (e.g., `astro dev`, `next dev`).
105+
106+
### 6. Pages Functions Migration (if applicable)
107+
108+
**ONLY if you have a `functions/` directory with .js/.ts files:**
109+
110+
- **Always add** the Pages Functions build command to your build process
111+
- Use: `wrangler pages functions build --outdir=<output>/_worker.js/`
112+
- This command converts Pages Functions to Workers format
113+
- Update your main field to point to the compiled functions: `"main": "./path/to/_worker.js"`
114+
- The presence of a `functions/` directory means you **must** include this build step
115+
116+
### 7. Validation and Deployment
117+
118+
1. Build your project to ensure it works
119+
2. Run `wrangler deploy --dry-run` to validate configuration
120+
3. Fix any issues identified
121+
4. Deploy with user permission using `wrangler deploy`
122+
123+
## Common Patterns
124+
125+
### Assets-Only Projects
126+
127+
Most static sites fall into this category:
128+
129+
```jsonc
130+
{
131+
"name": "my-site",
132+
"assets": { "directory": "./dist" },
133+
"compatibility_date": "2025-06-05",
134+
}
135+
```
136+
137+
### Projects with Workers Scripts
138+
139+
Sites with server-side logic or Pages Functions:
140+
141+
```jsonc
142+
{
143+
"name": "my-app",
144+
"main": "./dist/_worker.js",
145+
"assets": {
146+
"directory": "./dist",
147+
"binding": "ASSETS",
148+
},
149+
"compatibility_date": "2025-06-05",
150+
}
151+
```
152+
153+
**Build script example for projects with Pages Functions:**
154+
155+
```json
156+
{
157+
"scripts": {
158+
"build": "your-framework-build && wrangler pages functions build --outdir=./dist/_worker.js/"
159+
}
160+
}
161+
```
162+
163+
## Important Notes
164+
165+
- **Bindings**: Don't add KV, D1, or other bindings unless your build explicitly fails
166+
- **Framework Messages**: Ignore informational logs about storage or sessions
167+
- **Documentation**: Always check the official Cloudflare docs for the latest guidance
168+
- **Flexibility**: Adapt these guidelines to your specific project structure
169+
170+
## Migration Summary Format
171+
172+
When complete, document:
173+
174+
1. **Project Analysis**: What type of Pages project and its specific features
175+
2. **Migration Steps**: What changes were made and why
176+
3. **Validation**: How the migration was tested and verified

‎src/content/docs/workers/static-assets/migration-guides/migrate-from-pages.mdx‎

Lines changed: 11 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -26,7 +26,7 @@ Like Pages, requests for static assets on Workers are free, and Pages Functions
2626

2727
Unlike Pages, Workers has a distinctly broader set of features available to it, (including Durable Objects, Cron Triggers, and more comprehensive Observability). A complete list can be found at [the bottom of this page](#compatibility-matrix). Workers will receive the focus of Cloudflare's development efforts going forwards, so we therefore [are recommending using Cloudflare Workers over Cloudflare Pages for any new projects](http://blog.cloudflare.com/full-stack-development-on-cloudflare-workers).
2828

29-
## Migration guide
29+
## Migration
3030

3131
Migrating from Cloudflare Pages to Cloudflare Workers is often a straightforward process. The following are some of the most common steps you will need to take to migrate your project.
3232

@@ -373,6 +373,16 @@ Once you have validated the behavior of Worker, and are satisfied with the devel
373373

374374
<PackageManagers type="exec" pkg="wrangler" args={"pages project delete"} />
375375

376+
## Migrate your project using an AI coding assistant
377+
378+
You can add the following [experimental prompt](https://developers.cloudflare.com/workers/prompts/pages-to-workers.txt) in your preferred coding assistant (e.g. Claude Code, Cursor) to make your project compatible with Workers:
379+
380+
```
381+
https://developers.cloudflare.com/workers/prompts/pages-to-workers.txt
382+
```
383+
384+
You can also use the Cloudflare Documentation [MCP server](https://github.com/cloudflare/mcp-server-cloudflare/tree/main/apps/docs-vectorize) in your coding assistant to provide better context to your LLM when building with Workers, which includes this prompt when you ask to migrate from Pages to Workers.
385+
376386
## Compatibility matrix
377387

378388
This compatibility matrix compares the features of Workers and Pages. Unless otherwise stated below, what works in Pages works in Workers, and what works in Workers works in Pages. Think something is missing from this list? [Open a pull request](https://github.com/cloudflare/cloudflare-docs/edit/production/src/content/docs/workers/static-assets/compatibility-matrix.mdx) or [create a GitHub issue](https://github.com/cloudflare/cloudflare-docs/issues/new).

0 commit comments

Comments
 (0)