Edge Workers

Edge Workers run custom code in the WordPress VIP Edge, the content delivery network 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 and compiled to WebAssembly (WASM). The 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 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 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 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 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 describes how organization and application roles determine access to VIP-CLI. WordPress user roles do not grant VIP-CLI access.