Title: Edge Workers
Author: liranadia
Published: September 22, 2026

---

 1. [Infrastructure](https://docs.wpvip.com/infrastructure/)
 2. [Edge servers](https://docs.wpvip.com/infrastructure/edge-servers/)
 3. Edge Workers

#  Edge Workers

Edge Workers run custom code in the WordPress VIP Edge, the [content delivery network](https://developer.mozilla.org/en-US/docs/Glossary/CDN)
in front of every VIP application. They can change requests before cache lookup,
modify traffic between the cache and the origin application, and change responses
before delivery to the client. Use workers for request routing, redirects, response
headers, HTML rewriting, and integrations that need to run at the edge.

Workers are written in [AssemblyScript](https://www.assemblyscript.org/) and compiled
to [WebAssembly (WASM)](https://developer.mozilla.org/en-US/docs/WebAssembly). The
[vip-edge-workers-sdk](https://github.com/Automattic/vip-edge-workers-sdk) software
development kit (SDK) provides request and response handlers, outbound requests,
shared key-value storage (KV), rate limiting, URL and cookie helpers, and cryptographic
helpers. [VIP-CLI](https://docs.wpvip.com/vip-cli/) provides commands for building
and managing deployments.

## **How Edge Workers run**

An Edge Worker consists of a compiled `.wasm` file and configuration that identifies
its name, request scope, and runtime failure policy. An enabled worker runs in the
phases exported by its compiled code. A deployed but disabled worker does not handle
traffic.

The origin is the application server behind the VIP Edge. Workers interact with 
HTTP requests and responses around the cache and origin; their code does not execute
as a WordPress plugin or inside the origin’s Node.js process.

### **Request and response phases**

For a request that reaches the origin, the normal phase order is client request,
origin request, origin response, and client response. A cache hit skips the origin
phases.

| **Phase** | **SDK handler** | **When it runs** | **Example use** | 
| Client request | onClientRequest() | Before cache lookup. | Return a redirect, rewrite a request, or call an external service. | 
| Origin request | onOriginRequest() | On a cache miss, before forwarding to the origin. | Modify the request sent to the application. | 
| Origin response | onOriginResponse() | On a cache miss, after the origin responds. | Change response headers or cache directives before storage. | 
| Client response | onClientResponse() | After the cache path, before delivery to the client. | Add response headers to cached and origin responses. |

In request handlers, req.respondText() or req.respondWith() can return a response
without continuing to the origin. Client-request handlers can do this before cache
lookup.

Choose the phase according to which part of the request needs to change. For example,
the SDK’s [headers example](https://github.com/Automattic/vip-edge-workers-sdk/tree/0.5.0/examples/headers)
sets cache directives in the origin-response phase. A client-response header change
alone should not be treated as a change to an already-stored cache entry.

### **Isolation and shared state**

Each phase invocation starts with fresh worker memory. Module-level variables do
not retain values between phases or requests, including 2 phases of the same request.

Use request mutations, such as headers, to carry values forward through request 
phases. Use [KV](https://docs.wpvip.com/infrastructure/edge-servers/edge-workers/key-value/)
when a value needs to survive individual invocations. Do not place secrets in request
headers that might be forwarded to an unintended service.

## **Prerequisites**

To develop and manage Edge Workers, a developer must have:

 * Access to a VIP environment that supports Edge Workers.
 * An authenticated VIP-CLI version that includes vip edge-workers.
 * Node.js 22.19.0 or newer and npm 9 or newer for the documented build workflow.
 * The SDK and AssemblyScript compiler installed in the worker project.
 * A non-production environment for testing request behavior before production deployment.

Follow [Install VIP-CLI](https://docs.wpvip.com/vip-cli/installing-vip-cli/) for
installation and authentication. Use the dependency versions generated by vip edge-
workers init, and retain package-lock.json in version control so the reviewed dependency
tree can be reproduced.

These pages describe @automattic/vip-edge-workers-sdk 0.5.0. Before using the URL,
query, cookie, or redirect helpers, confirm that the project dependency and lockfile
contain SDK 0.5.0 or newer.

### **Roles and permissions**

Remote commands require permission to access the target application and environment.
[VIP Dashboard access](https://docs.wpvip.com/manage-user-access/vip-dashboard/)
describes how organization and application roles determine access to VIP-CLI. WordPress
user roles do not grant VIP-CLI access.

Last updated: September 22, 2026