Alibaba Cloud ESA Pages Deployment

Overview

ESA Pages is Alibaba Cloud's edge computing platform for static site hosting with global CDN acceleration. This skill automates deployment workflows for React/Vite applications.

Prerequisites

ESA CLI installed: npm install esa-cli@latest -g
Alibaba Cloud account with AccessKey configured
Logged in: esa-cli login

Quick Start

# Navigate to app directory
cd app

# Build and deploy
npm run build && esa-cli deploy

ESA CLI Commands

Authentication

# Login to ESA (requires AccessKey)
esa-cli login

# Logout
esa-cli logout

Deployment

# Deploy current directory (requires esa.jsonc)
esa-cli deploy

# Deploy with explicit entry
esa-cli deploy ./dist

# View deployments
esa-cli deployments

Project Management

# Initialize new project
esa-cli init my-project

# View project info
esa-cli project

# Manage sites
esa-cli site

Domain Management

# Add custom domain
esa-cli domain add your-domain.com

# List domains
esa-cli domain list

# Remove domain
esa-cli domain remove your-domain.com

Route Management

# Add route
esa-cli route add -r your-domain.com -s <site-name>

# List routes
esa-cli route list

Local Development

# Start local dev server
esa-cli dev

# Dev with custom port
esa-cli dev --port 3000

Configuration

esa.jsonc

{
  "name": "your-app-name",
  "assets": {
    "directory": "./dist",
    "notFoundStrategy": "singlePageApplication"
  },
  "dev": {
    "port": 18080
  }
}

Environment Variables

Production environment variables should be set in .env.local before build:

# Required
VITE_SUPABASE_URL=https://xxx.supabase.co
VITE_SUPABASE_ANON_KEY=eyJxxx...

# Production settings
VITE_ENABLE_MSW=false
VITE_LOG_LEVEL=info

Deployment Checklist

Close MSW Mock (VITE_ENABLE_MSW=false)
Verify environment variables are correct
Run npm run build successfully
Check dist/ directory exists
Verify esa.jsonc configuration
Run esa-cli deploy

Common Issues

"esa.jsonc not found"

Ensure you're in the correct directory containing esa.jsonc:

cd app && esa-cli deploy

"Not logged in"

esa-cli login

Build fails

# Check Node version (>= 20.x)
node -v

# Clean install
rm -rf node_modules && npm install

# Rebuild
npm run build

Large bundle warning

Consider code splitting:

// vite.config.ts
export default defineConfig({
  build: {
    rollupOptions: {
      output: {
        manualChunks: {
          'react-vendor': ['react', 'react-dom'],
          'ui-vendor': ['@radix-ui/react-dialog', '@radix-ui/react-dropdown-menu'],
        },
      },
    },
  },
});

Deployment Output

After successful deployment:

╔═══════════════════════════════════════════════════════════════════════╗
║ 🚀 Deploy Success                                                     ║
║                                                                       ║
║ APP  your-app-name                                                    ║
║ URL  https://your-app.xxx.er.aliyun-esa.net                           ║
║                                                                       ║
║ TIP  Add a custom domain: esa-cli domain add <DOMAIN>                 ║
╚═══════════════════════════════════════════════════════════════════════╝

References

Environment Configuration references/environment-config.md
Custom Domain Setup references/custom-domain.md
CI/CD Integration references/cicd-integration.md

esa-deploy