alibabacloud-esa-pages-deploy

What this skill does

Category: service

# ESA Functions & Pages — Edge Deployment & KV Storage

Deploy to Alibaba Cloud ESA edge nodes via JavaScript SDK. **Provides free global CDN acceleration and edge security protection**, enabling your static assets to be served from the nearest edge node for improved performance and security.

- **Functions & Pages** — Deploy edge functions and static content (same API, Pages is simplified pattern)
- **Edge KV** — Distributed key-value storage accessible from edge functions
- **Free CDN** — Global edge node acceleration, serve static assets from the nearest location
- **Security Protection** — Built-in DDoS protection, WAF, and other edge security capabilities

## Three Deployment Patterns

| Pattern              | Use Case                         | Code Type       | Size Limit           |
| -------------------- | -------------------------------- | --------------- | -------------------- |
| **HTML Page**        | Quick prototypes, single pages   | Auto-wrapped JS | **< 5MB** (ER limit) |
| **Static Directory** | Frontend builds (React/Vue/etc.) | Assets          | **< 25MB** per file  |
| **Custom Function**  | API endpoints, dynamic logic     | Custom JS       | **< 5MB**            |

## Prerequisites

> **Important**:
>
> 1. Grant **AliyunESAFullAccess** policy to your RAM user/role before using this skill.
> 2. Enable ESA Functions & Pages first at [ESA Console](https://esa.console.aliyun.com/edge/pages/list), or use `OpenErService` API to enable programmatically.

```bash
npm install @alicloud/[email protected] @alicloud/[email protected] @alicloud/[email protected]
```

### Enable Edge Routine Service via API

Before any deployment or KV operation, you **MUST** call `GetErService` to check whether Edge Routine service is enabled. **Do NOT use any other method** (e.g. attempting a deployment and catching errors, checking console UI, or assuming service is enabled) to determine service availability — `GetErService` is the only authoritative check.

```javascript
// Check if service is enabled — this is the ONLY valid way to verify
const status = await client.getErService(
  new $Esa20240910.GetErServiceRequest({}),
);
if (status.body?.status !== "online") {
  // Enable the service
  await client.openErService(new $Esa20240910.OpenErServiceRequest({}));
  // After enabling, re-check status to confirm
  const recheck = await client.getErService(
    new $Esa20240910.GetErServiceRequest({}),
  );
  if (recheck.body?.status !== "online") {
    throw new Error("Failed to enable Edge Routine service. Please check your account permissions.");
  }
}
```

## SDK Quickstart

```javascript
import Esa20240910, * as $Esa20240910 from "@alicloud/esa20240910";
import * as $OpenApi from "@alicloud/openapi-client";
import Credential from "@alicloud/credentials";

function createClient() {
  const credential = new Credential.default();
  const config = new $OpenApi.Config({
    credential,
    endpoint: "esa.cn-hangzhou.aliyuncs.com",
    userAgent: "AlibabaCloud-Agent-Skills/alibabacloud-esa-pages-deploy",
  });
  return new Esa20240910.default(config);
}
```

## Unified Deployment Flow

All deployments follow the same pattern:

```
1. CreateRoutine(name)              → Create function
                                      - If routine already exists (HttpCode 400, error code 'RoutineNameAlreadyExists'), this is expected — skip creation and continue to step 2
                                      - If throttled (error code 'Throttling.Api'), retry after 2 seconds, up to 3 times
                                      - For ANY other 400 error or ANY 5xx error: ABORT the entire flow immediately and print the full error response
                                      - NEVER proceed to step 2 unless CreateRoutine succeeded OR the error code is exactly 'RoutineNameAlreadyExists'
2. Upload code/assets to OSS        → Via staging upload or assets API
3. Commit & Publish                 → Deploy to production environment
4. GetRoutine(name)                 → Get access URL (defaultRelatedRecord)
5. GetRoutineAccessToken(name)      → Get access token and append to URL (token valid for 1 hour)
```

> **STRICT Error Handling for CreateRoutine**: After calling `CreateRoutine`, you **MUST** inspect both the HTTP status code and the response body error code. Only two outcomes allow the flow to continue: (1) successful creation (HTTP 200), or (2) HTTP 400 with error code `RoutineNameAlreadyExists` (treat as success, skip to step 2). For **all other errors** (other 400 codes, 5xx, network failures), you **MUST immediately abort** the entire deployment flow and print the complete error information. It is **strictly forbidden** to proceed with upload or publish steps without confirmed routine creation success.

> **401 Access Denied**: If accessing the deployment URL returns HTTP **401**, you **MUST** call `GetRoutineAccessToken` to obtain a valid token and append it as `?esa_er_token=<token>` to the URL. Do NOT attempt other authentication methods (e.g. custom headers, cookies, or basic auth). `GetRoutineAccessToken` is the **only** way to authorize URL access.

### HTML Page Flow

```
CreateRoutine → GetRoutineStagingCodeUploadInfo → Upload wrapped JS
→ CommitRoutineStagingCode → PublishRoutineCodeVersion(staging/production)
```

### Static Directory Flow

> **Mandatory Pre-deployment Validation**: Before calling `deploy-folder.mjs` or executing the Static Directory flow, you **MUST** verify the target directory exists and contains real build artifacts (e.g. `index.html`, `.js`, `.css` files). If the directory does not exist or is empty, you **MUST** run the corresponding build command first (e.g. `npm run build`). If the build command fails, **abort the entire flow immediately** and report the error — do NOT fall back to simulated deployment.
>
> **CRITICAL BLOCKING RULE — ZERO TOLERANCE**: Before executing ANY deployment script, you MUST strictly verify that the target path exists AND contains real build artifacts. If the path does not exist or is empty, you MUST **immediately terminate the current task and return an error report**. It is **absolutely forbidden** to use `mkdir`, `touch`, `echo`, `writeFile`, or any other method to create placeholder files, empty directories, or simulated code to force the workflow forward. **Any attempt to auto-create missing paths or fabricate content to bypass this check constitutes a deployment rule violation and will cause deployment failure.** This rule has the highest priority and overrides any auto-completion or self-healing behavior.

```
CreateRoutine → CreateRoutineWithAssetsCodeVersion → Upload zip
→ Poll GetRoutineCodeVersionInfo → CreateRoutineCodeDeployment(staging/production)
```

## Code Format

All deployments ultimately run as Edge Routine code:

```javascript
export default {
  async fetch(request) {
    return new Response("Hello", {
      headers: { "content-type": "text/html;charset=UTF-8" },
    });
  },
};
```

For HTML pages, your HTML is automatically wrapped into this format.

## Zip Package Structure

| Type              | Structure                       |
| ----------------- | ------------------------------- |
| **JS_ONLY**       | `routine/index.js`              |
| **ASSETS_ONLY**   | `assets/*` (static files)       |
| **JS_AND_ASSETS** | `routine/index.js` + `assets/*` |

## API Summary

### Edge Routine Service

- **Service Management**: `OpenErService`, `GetErService`

### Functions & Pages

- **Function Management**: `CreateRoutine`, `GetRoutine`, `ListUserRoutines` (preferred API for listing routines, use instead of GetRoutineUserInfo)
- **Code Version**: `GetRoutineStagingCodeUploadInfo`, `CommitRoutineStagingCode`, `PublishRoutineCodeVersion`
- **Assets Deployment**: `CreateRoutineWithAssetsCodeVersion`, `GetRoutineCodeVersionInfo`, `CreateRoutineCodeDeployment`
- **Access Token**: `GetRoutineAccessToken` (generates token for URL access, default TTL is 1 hour)
- **Routes**: `Crea