Manage Edge SSR (Cloudflare Workers) deployments: prebuilt-zip flow, server-side build flow, list history.
Actions:
- "create": Create a deployment from a locally-built zip; returns upload URL + deployment_id
- "start": Start the deployment after the zip is uploaded; polls until READY/ERROR (≤60s)
- "create_from_source": Server-side build — Mode 1: create deployment + return upload_url
- "start_from_source": Server-side build — Mode 2: kick off the build after source upload
- "list": List recent deployments (status, URL, sizes)
Two flows (pick ONE):
FLOW A — local build (you build with @cloudflare/next-on-pages locally):
1. Run `npx @cloudflare/next-on-pages` then zip the CONTENTS of `.vercel/output/static/`
(cd .vercel/output/static && zip -r ../../../edge-ssr.zip .)
On Windows use Git Bash or WSL; built-in zip tools use backslashes which break uploads.
2. action: "create" → { deployment_id, uploadUrl, expiresIn }
3. PUT zip to uploadUrl with Content-Type: application/zip
4. action: "start" → polls; returns { url, status: "READY" }
FLOW B — server-side build (Butterbase runs the build for you):
1. action: "create_from_source" → { deployment_id, upload_url, max_source_bytes }
2. PUT source zip (≤50 MB) to upload_url with Content-Type: application/zip
3. action: "start_from_source" with deployment_id + lockfile_hash (sha256 of package-lock.json)
→ { build_id, status, logs_url, status_url }
4. Stream logs_url for live build output; poll status_url for terminal status
Parameters by action:
create: { app_id, action, framework? }
start: { app_id, action, deployment_id }
create_from_source: { app_id, action, framework? }
start_from_source: { app_id, action, deployment_id, lockfile_hash, build_command?, output_dir?, package_manager?, user_env? }
list: { app_id, action, limit? }
framework: "nextjs-edge" (default) | "remix-edge" | "other-edge"
Status values: WAITING | UPLOADING | BUILDING | READY | ERROR | CANCELED | TIMEOUT
On TIMEOUT: deployment did not reach a terminal state within 60s. Use action: "list" to check
the current status, or call "start" again if it is still BUILDING.
Plan limits: Free = 1 deployment per app (replaces previous). Starter+ = unlimited.
Common errors:
- INVALID_STATUS / UPLOAD_EXPIRED: zip not uploaded before "start"
- STATE_PREREQUISITE_MISSING: source zip not uploaded before "start_from_source"
- QUOTA_FILE_SIZE_EXCEEDED: source zip exceeds 50 MB
- RESOURCE_NOT_FOUND: app or deployment doesn't exist
- EXTERNAL_CLOUDFLARE_ERROR: Workers for Platforms not configured
Build caching (start_from_source):
lockfile_hash is the node_modules cache key — same hash means cached node_modules (faster builds).
Compute it with: sha256sum package-lock.json | cut -d' ' -f1