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: Enable ESA Functions & Pages first at ESA Console before using this skill, 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

If the user hasn't enabled the Edge Routine service, call OpenErService to enable it:

// Check if service is enabled
const status = await client.getErService(
  new $Esa20240910.GetErServiceRequest({}),
);
if (status.body?.status !== "online") {
  // Enable the service
  await client.openErService(new $Esa20240910.OpenErServiceRequest({}));
}

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();
  const config = new $OpenApi.Config({
    credential,
    endpoint: "esa.cn-hangzhou.aliyuncs.com",
    userAgent: "AlibabaCloud-Agent-Skills",
  });
  return new Esa20240910(config);
}

Unified Deployment Flow

All deployments follow the same pattern:

1. CreateRoutine(name)              → Create function (skip if exists)
2. Upload code/assets to OSS        → Via staging upload or assets API
3. Commit & Publish                 → Deploy to staging → production
4. GetRoutine(name)                 → Get access URL (defaultRelatedRecord)

HTML Page Flow

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

Static Directory Flow

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

Code Format

All deployments ultimately run as Edge Routine code:

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
• Code Version: GetRoutineStagingCodeUploadInfo, CommitRoutineStagingCode, PublishRoutineCodeVersion
• Assets Deployment: CreateRoutineWithAssetsCodeVersion, GetRoutineCodeVersionInfo, CreateRoutineCodeDeployment
• Routes: CreateRoutineRoute, ListRoutineRoutes

Edge KV

• Namespace: CreateKvNamespace, GetKvNamespace, GetKvAccount
• Key Operations: PutKv, GetKv, ListKvs
• Batch Operations: BatchPutKv
• High Capacity: PutKvWithHighCapacity, BatchPutKvWithHighCapacity

Utility Scripts

Pre-made scripts for common operations. Install dependencies first:

npm install @alicloud/esa20240910@2.43.0 @alicloud/openapi-client@0.4.15 @alicloud/credentials@2.4.4 @alicloud/tea-util@1.4.9 jszip@3.10.1

| Script | Usage | Description | | --------------------- | ----------------------------------------------------- | ----------------------- | | deploy-html.mjs | node scripts/deploy-html.mjs <name> <html-file> | Deploy HTML page | | deploy-folder.mjs | node scripts/deploy-folder.mjs <name> <folder> | Deploy static directory | | deploy-function.mjs | node scripts/deploy-function.mjs <name> <code-file> | Deploy custom function | | manage.mjs | node scripts/manage.mjs list\|get | Manage routines |

Examples:

# Deploy HTML page
node scripts/deploy-html.mjs my-page index.html

# Deploy React/Vue build
node scripts/deploy-folder.mjs my-app ./dist

# Deploy custom function
node scripts/deploy-function.mjs my-api handler.js

# List all routines
node scripts/manage.mjs list

# Get routine details
node scripts/manage.mjs get my-page

Key Notes

• Function name: lowercase letters/numbers/hyphens, start with letter, length ≥ 2
• Same name: Reuses existing function, deploys new version
• Environments: staging → production (both by default)
• Access URL: defaultRelatedRecord from GetRoutine
• Size limits: Functions < 5MB, Assets single file < 25MB, KV value < 2MB (25MB high capacity)

Credentials

The SDK uses Alibaba Cloud default credential chain. No explicit AK/SK configuration needed.

Note: ESA endpoint is fixed (esa.cn-hangzhou.aliyuncs.com), no region needed.

Reference

• Functions & Pages API: references/pages-api.md
• Edge KV API: references/kv-api.md