EdgeOne Pages Development Guide
Develop full-stack applications on EdgeOne Pages — Edge Functions, Cloud Functions (Node.js / Go / Python), and Middleware.
When to use this skill
- Creating APIs, serverless functions, or backend logic on EdgeOne Pages
- Adding middleware for request interception, redirects, auth guards, or A/B testing
- Building full-stack apps with static frontend + server-side functions
- Using KV Storage for edge-side persistent data
- Setting up WebSocket endpoints (Node.js runtime)
- Integrating Express, Koa, Gin, Echo, Flask, FastAPI, or Django on EdgeOne Pages
- Debugging EdgeOne Pages runtime errors (function failures, middleware issues, KV problems)
Do NOT use for:
- Deployment → use
edgeone-pages-deploy skill
- Next.js / Nuxt middleware or API routes → use the framework's own API, NOT the platform
middleware.js
- Generic Express/Koa/Gin/Flask development outside an EdgeOne Pages project
- Cloudflare Workers, Vercel Functions, or other platforms
How to use this skill (for a coding agent)
- Read the Decision Tree below to pick the correct runtime
- Follow the Routing table to load the relevant reference file
- Use the code patterns from that reference to implement the user's request
⛔ Critical Rules (never skip)
- Choose the right runtime for the task. Follow the Decision Tree — never guess.
- Edge Functions run on V8, NOT Node.js. Never use Node.js built-in modules (
fs, path, crypto from Node) or npm packages in Edge Functions.
- Cloud Functions support three runtimes: Node.js, Go, and Python. Place all function files under
cloud-functions/ directory. The platform detects the language by file extension (.js/.ts → Node.js, .go → Go, .py → Python).
- Node.js functions return a standard Web
Response object, not res.send() — unless using Express/Koa via the [[default]].js pattern.
- Go Handler mode requires
http.HandlerFunc signature; Framework mode uses standard framework code with auto port/path adaptation.
- Python entry files are identified by class/app patterns (
class handler(BaseHTTPRequestHandler), app = Flask(...), app = FastAPI(...)). Other .py files are treated as helper modules.
- Middleware is for lightweight request interception only. Never put heavy computation or database calls in middleware.
- Always use
edgeone pages dev for local development. Never run a separate dev server for functions — the CLI handles everything on port 8088.
- Never configure
edgeone pages dev as the devCommand in edgeone.json or as the dev script in package.json — this causes infinite recursion.
- For framework projects (Next.js, Nuxt, etc.), use the framework's own middleware — NOT the platform
middleware.js.
Technology Decision Tree
Request interception / redirect / rewrite / auth guard / A/B test?
→ Middleware → read references/middleware.md
Lightweight API with ultra-low latency (simple logic, no npm)?
→ Edge Functions → read references/edge-functions.md
KV persistent storage? (⚠️ enable KV in console first)
→ Edge Functions + KV Storage → read references/kv-storage.md
Complex backend with npm packages / database / WebSocket?
→ Cloud Functions (Node.js) → read references/node-functions.md
Express or Koa framework?
→ Cloud Functions (Node.js) with [[default]].js → read references/node-functions.md
High-performance API with Go (Gin / Echo / Chi / Fiber)?
→ Cloud Functions (Go) → read references/go-functions.md
Python API with Flask / FastAPI / Django / Sanic?
→ Cloud Functions (Python) → read references/python-functions.md
Pure static site with no server-side logic?
→ No functions needed — just deploy static files
Need a project structure template?
→ read references/recipes.md
Runtime Comparison
| Feature |
Edge Functions |
Cloud Functions (Node.js) |
Cloud Functions (Go) |
Cloud Functions (Python) |
Middleware |
| Runtime |
V8 (like CF Workers) |
Node.js v20.x |
Go 1.26+ |
Python 3.10 |
V8 (edge) |
| npm/packages |
❌ Not supported |
✅ Full npm ecosystem |
✅ Go modules |
✅ pip (auto-detect) |
❌ Not supported |
| Max code size |
5 MB |
128 MB |
128 MB |
128 MB (incl. deps) |
Part of edge bundle |
| Max request body |
1 MB |
6 MB |
6 MB |
6 MB |
N/A (passes through) |
| Max CPU / wall time |
200 ms CPU |
120 s wall clock |
120 s wall clock |
120 s wall clock |
Lightweight only |
| KV Storage |
✅ Yes (global variable) |
❌ No |
❌ No |
❌ No |
❌ No |
| WebSocket |
❌ No |
✅ Yes |
❌ No |
❌ No |
❌ No |
| Framework support |
— |
Express, Koa |
Gin, Echo, Chi, Fiber |
Flask, FastAPI, Django, Sanic |
— |
| Use case |
Lightweight APIs, edge compute |
Complex APIs, full-stack |
High-perf APIs, compiled speed |
Data science, ML, rapid prototyping |
Request preprocessing |
Cloud Functions — Language Comparison
| Feature |
Node.js |
Go |
Python |
| File extension |
.js / .ts |
.go |
.py |
| Handler style |
export function onRequest(ctx) → Response |
func Handler(w, r) (Handler) or func main() (Framework) |
class handler(BaseHTTPRequestHandler) or framework app instance |
| Framework mode |
Express/Koa via [[default]].js |
Gin/Echo/Chi/Fiber via entry .go file |
Flask/FastAPI/Django via entry .py file |
| Dependency management |
package.json (npm) |
go.mod (auto) |
requirements.txt + auto-detect |
| Dev modes |
Handler / Framework |
Handler / Framework |
Handler / WSGI / ASGI |
Routing
| Task |
Read |
| Edge Functions (lightweight APIs, V8 runtime, KV Storage) |
references/edge-functions.md |
| KV Storage (persistent key-value storage on edge) |
references/kv-storage.md |
| Cloud Functions — Node.js (npm, database, Express/Koa, WebSocket) |
references/node-functions.md |
| Cloud Functions — Go (Gin, Echo, Chi, Fiber, net/http) |
references/go-functions.md |
| Cloud Functions — Python (Flask, FastAPI, Django, Sanic, Handler) |
references/python-functions.md |
| Middleware (redirects, rewrites, auth guards, A/B testing) |
references/middleware.md |
| Project structure templates and common recipes |
references/recipes.md |
| Debugging and troubleshooting |
references/troubleshooting.md |
Project Setup (Quick Start)
Initialize the project:
edgeone pages init
Start local development:
edgeone pages dev # Serves everything on http://localhost:8088/
Link project (required for KV & env vars):
edgeone pages link
Manage environment variables:
edgeone pages env pull # Pull from console to local .env
Access env vars in functions via context.env.KEY (Node.js), os.Getenv("KEY") (Go), or os.environ.get("KEY") (Python).
For detailed project structures and recipes, see references/recipes.md.
1---2name: edgeone-pages-dev3description: This skill guides development of full-stack features on EdgeOne Pages — Edge Functions, Cloud Functions (Node.js / Go / Python runtimes), Middleware, KV Storage, and local dev workflows. It should be used when the user wants to create APIs, serverless functions, middleware, WebSocket endpoints, or full-stack features specifically on EdgeOne Pages — e.g. "create an API", "add a serverless function", "write middleware", "build a full-stack app", "add WebSocket support", "set up edge functions", "use KV storage", "create a Go API", "build a Python backend", "use Flask/FastAPI/Gin on EdgeOne Pages". Do NOT trigger for framework-native features (Next.js API routes, Next.js middleware, Nuxt server routes) or generic Express/Koa development outside an EdgeOne Pages project. Do NOT trigger for deployment — use edgeone-pages-deploy instead. Do NOT trigger for other platforms (Cloudflare Workers, Vercel Functions, AWS Lambda).4---56# EdgeOne Pages Development Guide78Develop full-stack applications on **EdgeOne Pages** — Edge Functions, Cloud Functions (Node.js / Go / Python), and Middleware.910## When to use this skill1112- Creating APIs, serverless functions, or backend logic on EdgeOne Pages13- Adding middleware for request interception, redirects, auth guards, or A/B testing14- Building full-stack apps with static frontend + server-side functions15- Using KV Storage for edge-side persistent data16- Setting up WebSocket endpoints (Node.js runtime)17- Integrating Express, Koa, Gin, Echo, Flask, FastAPI, or Django on EdgeOne Pages18- Debugging EdgeOne Pages runtime errors (function failures, middleware issues, KV problems)1920**Do NOT use for:**21- Deployment → use `edgeone-pages-deploy` skill22- Next.js / Nuxt middleware or API routes → use the framework's own API, NOT the platform `middleware.js`23- Generic Express/Koa/Gin/Flask development outside an EdgeOne Pages project24- Cloudflare Workers, Vercel Functions, or other platforms2526## How to use this skill (for a coding agent)27281. Read the **Decision Tree** below to pick the correct runtime292. Follow the **Routing** table to load the relevant reference file303. Use the code patterns from that reference to implement the user's request3132## ⛔ Critical Rules (never skip)33341. **Choose the right runtime for the task.** Follow the Decision Tree — never guess.352. **Edge Functions run on V8, NOT Node.js.** Never use Node.js built-in modules (`fs`, `path`, `crypto` from Node) or npm packages in Edge Functions.363. **Cloud Functions support three runtimes: Node.js, Go, and Python.** Place all function files under `cloud-functions/` directory. The platform detects the language by file extension (`.js`/`.ts` → Node.js, `.go` → Go, `.py` → Python).374. **Node.js functions return a standard Web `Response` object**, not `res.send()` — unless using Express/Koa via the `[[default]].js` pattern.385. **Go Handler mode** requires `http.HandlerFunc` signature; **Framework mode** uses standard framework code with auto port/path adaptation.396. **Python entry files** are identified by class/app patterns (`class handler(BaseHTTPRequestHandler)`, `app = Flask(...)`, `app = FastAPI(...)`). Other `.py` files are treated as helper modules.407. **Middleware is for lightweight request interception only.** Never put heavy computation or database calls in middleware.418. **Always use `edgeone pages dev` for local development.** Never run a separate dev server for functions — the CLI handles everything on port 8088.429. **Never configure `edgeone pages dev` as the `devCommand` in `edgeone.json` or as the `dev` script in `package.json`** — this causes infinite recursion.4310. **For framework projects (Next.js, Nuxt, etc.), use the framework's own middleware** — NOT the platform `middleware.js`.4445---4647## Technology Decision Tree4849```50Request interception / redirect / rewrite / auth guard / A/B test?51 → Middleware → read references/middleware.md5253Lightweight API with ultra-low latency (simple logic, no npm)?54 → Edge Functions → read references/edge-functions.md5556KV persistent storage? (⚠️ enable KV in console first)57 → Edge Functions + KV Storage → read references/kv-storage.md5859Complex backend with npm packages / database / WebSocket?60 → Cloud Functions (Node.js) → read references/node-functions.md6162Express or Koa framework?63 → Cloud Functions (Node.js) with [[default]].js → read references/node-functions.md6465High-performance API with Go (Gin / Echo / Chi / Fiber)?66 → Cloud Functions (Go) → read references/go-functions.md6768Python API with Flask / FastAPI / Django / Sanic?69 → Cloud Functions (Python) → read references/python-functions.md7071Pure static site with no server-side logic?72 → No functions needed — just deploy static files7374Need a project structure template?75 → read references/recipes.md76```7778### Runtime Comparison7980| Feature | Edge Functions | Cloud Functions (Node.js) | Cloud Functions (Go) | Cloud Functions (Python) | Middleware |81|---------|--------------|--------------------------|---------------------|------------------------|------------|82| **Runtime** | V8 (like CF Workers) | Node.js v20.x | Go 1.26+ | Python 3.10 | V8 (edge) |83| **npm/packages** | ❌ Not supported | ✅ Full npm ecosystem | ✅ Go modules | ✅ pip (auto-detect) | ❌ Not supported |84| **Max code size** | 5 MB | 128 MB | 128 MB | 128 MB (incl. deps) | Part of edge bundle |85| **Max request body** | 1 MB | 6 MB | 6 MB | 6 MB | N/A (passes through) |86| **Max CPU / wall time** | 200 ms CPU | 120 s wall clock | 120 s wall clock | 120 s wall clock | Lightweight only |87| **KV Storage** | ✅ Yes (global variable) | ❌ No | ❌ No | ❌ No | ❌ No |88| **WebSocket** | ❌ No | ✅ Yes | ❌ No | ❌ No | ❌ No |89| **Framework support** | — | Express, Koa | Gin, Echo, Chi, Fiber | Flask, FastAPI, Django, Sanic | — |90| **Use case** | Lightweight APIs, edge compute | Complex APIs, full-stack | High-perf APIs, compiled speed | Data science, ML, rapid prototyping | Request preprocessing |9192### Cloud Functions — Language Comparison9394| Feature | Node.js | Go | Python |95|---------|---------|-----|--------|96| **File extension** | `.js` / `.ts` | `.go` | `.py` |97| **Handler style** | `export function onRequest(ctx)` → `Response` | `func Handler(w, r)` (Handler) or `func main()` (Framework) | `class handler(BaseHTTPRequestHandler)` or framework app instance |98| **Framework mode** | Express/Koa via `[[default]].js` | Gin/Echo/Chi/Fiber via entry `.go` file | Flask/FastAPI/Django via entry `.py` file |99| **Dependency management** | `package.json` (npm) | `go.mod` (auto) | `requirements.txt` + auto-detect |100| **Dev modes** | Handler / Framework | Handler / Framework | Handler / WSGI / ASGI |101102---103104## Routing105106| Task | Read |107|------|------|108| Edge Functions (lightweight APIs, V8 runtime, KV Storage) | [references/edge-functions.md](references/edge-functions.md) |109| KV Storage (persistent key-value storage on edge) | [references/kv-storage.md](references/kv-storage.md) |110| Cloud Functions — Node.js (npm, database, Express/Koa, WebSocket) | [references/node-functions.md](references/node-functions.md) |111| Cloud Functions — Go (Gin, Echo, Chi, Fiber, net/http) | [references/go-functions.md](references/go-functions.md) |112| Cloud Functions — Python (Flask, FastAPI, Django, Sanic, Handler) | [references/python-functions.md](references/python-functions.md) |113| Middleware (redirects, rewrites, auth guards, A/B testing) | [references/middleware.md](references/middleware.md) |114| Project structure templates and common recipes | [references/recipes.md](references/recipes.md) |115| Debugging and troubleshooting | [references/troubleshooting.md](references/troubleshooting.md) |116117---118119## Project Setup (Quick Start)120121Initialize the project:122123```bash124edgeone pages init125```126127Start local development:128129```bash130edgeone pages dev # Serves everything on http://localhost:8088/131```132133Link project (required for KV & env vars):134135```bash136edgeone pages link137```138139Manage environment variables:140141```bash142edgeone pages env pull # Pull from console to local .env143```144145Access env vars in functions via `context.env.KEY` (Node.js), `os.Getenv("KEY")` (Go), or `os.environ.get("KEY")` (Python).146147For detailed project structures and recipes, see [references/recipes.md](references/recipes.md).
edgeone-pages