Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion config/source/guideline/cloudbase/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -375,7 +375,7 @@ When users request deployment to CloudBase:
1. **Backend Deployment (if applicable)**:
- Only for Node.js cloud functions: deploy directly using `manageFunctions(action="createFunction")` / `manageFunctions(action="updateFunctionCode")`
- Legacy compatibility: if older materials mention `createFunction`, `updateFunctionCode`, or `getFunctionList`, map them to `manageFunctions(...)` and `queryFunctions(...)`
- Before deploying, decide whether the function is Event or HTTP. Event Functions use `exports.main = async (event, context) => {}`.
- Before deploying, decide whether the function is Event or HTTP. Event Functions use `exports.main = async (event, context) => {}` and must use CommonJS (`require()`, `exports.main`) — do not use `import`/`export` syntax in Event Functions.
- HTTP Functions are standard web services: they must listen on port `9000`, include `scf_bootstrap`, and for Node.js should default to native `http.createServer((req, res) => { ... })`. Parse `req.url` and the streamed request body manually, set response headers explicitly, and do not write the function as `exports.main` unless you intentionally choose Functions Framework.
- **Alternative: CLI Deployment** — If MCP is unavailable or the user prefers CLI, read the `cloudbase-cli` skill for `tcb`-based deployment workflows (functions, CloudRun, hosting).
- For other languages backend server (Java, Go, PHP, Python, Node.js): deploy to Cloud Run
Expand Down
1 change: 1 addition & 0 deletions config/source/skills/cloud-functions/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -49,6 +49,7 @@ Keep local `references/...` paths for files that ship with the current skill dir
- Picking the wrong function type and trying to compensate later.
- Confusing official CloudBase API client work with building your own HTTP function.
- Mixing Event Function code shape (`exports.main(event, context)`) with HTTP Function code shape (`req` / `res` on port `9000`).
- Using ES Module syntax (`import ...`, `export ...`) in Event Functions. Event Functions run in a CommonJS environment — always use `require()` and `exports.main`. Using `import` will cause a `require is not defined` or `Cannot use import statement outside a module` runtime error.
- Treating HTTP Access as the implementation model for HTTP Functions. HTTP Access is a gateway configuration for Event Functions, not the HTTP Function runtime model.
- Assuming `db.collection("name").add(...)` will create a missing document-database collection automatically. Collection creation is a separate management step.
- Forgetting that runtime cannot be changed after creation.
Expand Down
12 changes: 7 additions & 5 deletions config/source/skills/cloud-functions/checklist.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,15 +7,17 @@ Use this checklist before creating or updating a CloudBase function.
1. Decide whether this is an Event Function or an HTTP Function.
- Event Function: `exports.main(event, context)`, SDK/timer driven
- HTTP Function: `req` / `res`, listens on port `9000`
2. Pick the runtime before creation and state it explicitly.
3. For HTTP Functions, confirm `scf_bootstrap` exists and the Node.js binary path matches the runtime (e.g. `Nodejs18.15` → `/var/lang/node18/bin/node`).
4. Confirm the function root path points to the parent directory, not the function directory itself.
5. For HTTP Functions that need anonymous access, configure the function security rule with `managePermissions(action="updateResourcePermission", resourceType="function")` after creation. Default rules reject anonymous callers with `EXCEED_AUTHORITY`.
6. If the request is really for a long-running container service, reroute to `cloudrun-development`.
2. For Event Functions, confirm the code uses CommonJS: `require()` for imports, `exports.main` for the handler. Do not use `import` or `export` syntax — the runtime is CommonJS only.
3. Pick the runtime before creation and state it explicitly.
4. For HTTP Functions, confirm `scf_bootstrap` exists and the Node.js binary path matches the runtime (e.g. `Nodejs18.15` → `/var/lang/node18/bin/node`).
5. Confirm the function root path points to the parent directory, not the function directory itself.
6. For HTTP Functions that need anonymous access, configure the function security rule with `managePermissions(action="updateResourcePermission", resourceType="function")` after creation. Default rules reject anonymous callers with `EXCEED_AUTHORITY`.
7. If the request is really for a long-running container service, reroute to `cloudrun-development`.

## Common failure patterns

- Choosing the wrong function type and compensating later.
- Using ES Module syntax (`import`, `export`) in Event Functions instead of CommonJS (`require()`, `exports.main`).
- Mixing Event Function and HTTP Function handler shapes in the same implementation.
- Forgetting that runtime cannot be changed after creation.
- Mismatching the `scf_bootstrap` Node.js binary path with the function runtime.
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,37 @@ Use this reference when the task is clearly about an Event Function (`exports.ma
- Event Functions auto-install dependencies from `package.json` during deployment, so you normally do not ship `node_modules`.
- The function root path must point to the parent directory that contains the function folder.

## Minimal structure
## Module system: CommonJS only

Event Functions run in a **CommonJS** Node.js environment. This has important implications for how you write function code:

- **Use `require()` to import dependencies** — not `import`. The Event Function runtime does not support ES Module syntax.
- **Use `exports.main` or `module.exports` to export the handler** — the `exports.main = async (event, context) => {}` pattern is CommonJS.
- **Do not add `"type": "module"` to `package.json`** — this will cause the function to fail at runtime with `require is not defined` or `Cannot use import statement outside a module`.
- **Do not use `import ... from ...` syntax** in Event Function code. If you need the `wx-server-sdk` or `@cloudbase/node-sdk`, load it with `require()`.

```javascript
// ✅ Correct: CommonJS in Event Function
const cloud = require("wx-server-sdk");
cloud.init();

exports.main = async (event, context) => {
const wxContext = cloud.getWXContext();
return {
OPENID: wxContext.OPENID,
APPID: wxContext.APPID,
};
};
```

```javascript
// ❌ Wrong: ESM in Event Function — will fail at runtime
import cloud from "wx-server-sdk"; // SyntaxError: Cannot use import statement

export const main = async (event, context) => { ... }; // Also wrong
```

### Minimal structure

```text
cloudfunctions/
Expand Down
Loading