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)

1. Read the Decision Tree below to pick the correct runtime
2. Follow the Routing table to load the relevant reference file
3. Use the code patterns from that reference to implement the user's request

⛔ Critical Rules (never skip)

1. Choose the right runtime for the task. Follow the Decision Tree — never guess.
2. 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.
3. 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).
4. Node.js functions return a standard Web Response object, not res.send() — unless using Express/Koa via the [[default]].js pattern.
5. Go Handler mode requires http.HandlerFunc signature; Framework mode uses standard framework code with auto port/path adaptation.
6. Python entry files are identified by class/app patterns (class handler(BaseHTTPRequestHandler), app = Flask(...), app = FastAPI(...)). Other .py files are treated as helper modules.
7. Middleware is for lightweight request interception only. Never put heavy computation or database calls in middleware.
8. Always use edgeone pages dev for local development. Never run a separate dev server for functions — the CLI handles everything on port 8088.
9. Never configure edgeone pages dev as the devCommand in edgeone.json or as the dev script in package.json — this causes infinite recursion.
10. 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

Cloud Functions — Language Comparison

Routing

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](references/recipes.md).