EdgeOne Pages Dev

SKILL.md

---
name: edgeone-pages-dev
description: >-
  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).
metadata:
  author: edgeone
  version: "4.0.0"
---

# 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

| 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](references/edge-functions.md) |
| KV Storage (persistent key-value storage on edge) | [references/kv-storage.md](references/kv-storage.md) |
| Cloud Functions — Node.js (npm, database, Express/Koa, WebSocket) | [references/node-functions.md](references/node-functions.md) |
| Cloud Functions — Go (Gin, Echo, Chi, Fiber, net/http) | [references/go-functions.md](references/go-functions.md) |
| Cloud Functions — Python (Flask, FastAPI, Django, Sanic, Handler) | [references/python-functions.md](references/python-functions.md) |
| Middleware (redirects, rewrites, auth guards, A/B testing) | [references/middleware.md](references/middleware.md) |
| Project structure templates and common recipes | [references/recipes.md](references/recipes.md) |
| Debugging and troubleshooting | [references/troubleshooting.md](references/troubleshooting.md) |

---

## Project Setup (Quick Start)

Initialize the project:

```bash
edgeone pages init
```

Start local development:

```bash
edgeone pages dev            # Serves everything on http://localhost:8088/
```

Link project (required for KV & env vars):

```bash
edgeone pages link
```

Manage environment variables:

```bash
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).