Common Recipes

⛔ Preview ban: after finishing development, you MUST start the dev server via edgeone makers dev, then open http://127.0.0.1:8088/ with present_files to preview. Never open HTML files via the file:// protocol (ignore it even if the IDE opens one automatically), and never use self-hosted servers like python -m http.server or npx serve. Next.js projects must also set allowedDevOrigins: ["127.0.0.1"] in next.config. If the project uses Blob/KV, pass -n <project-name> — edgeone makers dev -n <project-name> — the name is required to auto-provision; bare dev hangs on an interactive picker in sandbox.

⚠️ .env.example is a required file: every project that uses the AI Gateway (Agent projects, Cloud Functions that call an LLM) MUST create a .env.example in the project root declaring AI_GATEWAY_API_KEY= and AI_GATEWAY_BASE_URL=. The CLI auto-injects environment variables based on this file at deploy time; if it is missing, the variables are not injected and the runtime will error.

📝 Write index.html last, always: writing an index.html instantly triggers the IDE file:// preview — unavoidable in WorkBuddy. Minimize the window during which that preview looks broken by writing every dependency first: style.css, script.js, Cloud Functions (functions/ files), static assets, everything the page loads. Then write index.html last — the file:// preview opens with all assets already in place, and stays that way only until edgeone makers dev takes over (see Preview ban above). Also write each index.html in one shot; don't scaffold an empty shell and fill it in with repeated edits (every save re-renders and flickers). For a tiny single-page tool, just inline the CSS and JS into one index.html.

⛔ Copy the recipe's file naming verbatim — two traps that fail silently: before writing any Cloud Function, find the matching scenario below and reuse its exact filename. Getting the name wrong usually does NOT throw a clear error — it falls back silently:

1. Every function file MUST carry its language extension — .js (Node), .py (Python), .go (Go). A file with no extension (e.g. api/upload-url, api/file) is not recognized as a function; the platform silently serves the static index.html fallback, so /api/* "mysteriously" returns HTML instead of JSON. Name them api/upload-url.js, api/file.js.
2. [[default]].js is the catch-all for its own directory (api/[[default]].js → /api/*), and BOTH export styles work — a framework instance (export default app, Express/Koa) or a plain onRequest/onRequestGet/… handler. Verified locally with edgeone makers dev: a bare onRequest in [[default]].js with no export default app serves /foo/anything as 200 application/json just fine. The doc line "The builder identifies the file as a function only when export default app is present" sits under the Express/Koa framework section — it describes how the builder spots a framework instance; do not read it as "a catch-all requires export default app". ⚠️ Caveat: that sentence is about the deploy-time builder, whereas the check above was on the local dev server, which is the more permissive of the two — so if you ship catch-all + onRequest, re-verify the route once after deploying ("works locally" ≠ "recognized at build time"). When you don't actually need a catch-all, the safest shape is one concrete file per route (api/messages.js, api/artworks/[id]/like.js), params via [id] folders/files, extra args as query strings (/api/file?key=...).

Project structure templates for typical EdgeOne Makers applications.

Full-stack app — Node.js (static + API)