/alibabacloud-esa-pages-deploy

name: alibabacloud-esa-pages-deploy
description: Deploy HTML pages, static directories, or custom edge functions to Alibaba Cloud ESA edge nodes. Manage Edge KV for distributed key-value storage. Use when deploying web pages, static sites, frontend builds, serverless edge functions, or edge data storage to ESA Functions & Pages.

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.

npm install @alicloud/esa20240910@2.43.0 @alicloud/openapi-client@0.4.15 @alicloud/credentials@2.4.4

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.

// 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

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 c