Developing a worker
The supported CLI toolchain is AssemblyScript. Although its syntax resembles TypeScript, worker code compiles to WASM rather than JavaScript. SDK methods such as fetch() and body readers are synchronous; they do not return promises.
Creating a project
VIP-CLI command examples
The examples use the application name example-app and environment develop. Replace these values with the intended target. Target environments with VIP-CLI commands describes application and environment aliases. Local init, new, and build commands do not take an environment target.
- Create a project in
edge-workers/:
vip edge-workers init- Change to the project directory:
cd edge-workers- Install the generated dependencies:
npm install- Create a worker scoped to paths beginning with
/edge-example/:
vip edge-workers new response-headers --location starts_with:/edge-example/The worker’s configuration is stored in workers/response-headers/worker.json. Its source entry file is workers/response-headers/assembly/index.ts. Shared AssemblyScript modules can be kept in lib/ within the project.
Initialization requires an absent or empty destination directory. To choose another destination, pass a directory to init; use --path on subsequent local project commands when needed.
Adding a response header
Replace workers/response-headers/assembly/index.ts with:
import { Response, onClientResponse } from "@automattic/vip-edge-workers-sdk";
export {
alloc,
on_client_response,
} from "@automattic/vip-edge-workers-sdk/assembly/index";
onClientResponse((response: Response): void => {
response.headers.set("x-edge-example", "enabled");
});
This worker adds a header to matching responses without reading or changing their bodies. The SDK’s alloc export is required. Export the entry point for each implemented phase:
| Handler | Required phase export |
|---|---|
| onClientRequest() | on_client_request |
| onOriginRequest() | on_origin_request |
| onOriginResponse() | on_origin_response |
| onClientResponse() | on_client_response |
Only export phases with implemented handlers. The generated starter exports the client-response phase; examples of other phases are commented out.
Configuring request scope
worker.json defines the worker’s name, source entry file, and optional request scope:
{
"name": "response-headers",
"entry": "assembly/index.ts",
"location": {
"operator": "starts_with",
"value": "/edge-example/"
}
}| Field | Purpose |
|---|---|
| name | Required name, unique within the target environment; maximum 64 characters. |
| entry | Required source path relative to the worker directory; must remain inside that directory. |
| location | Optional request-matching rule with a nonempty value. Operators: contains, equals, starts_with, ends_with. |
| on_failure | Optional runtime failure policy; accepts continue or error. |
Names must be valid portable filenames. Use a name such as response-headers; path separators, control characters, Windows-reserved names, and trailing dots or spaces are rejected.
Location configuration has different effects when creating and updating a worker:
| location in the manifest | New worker | Existing worker |
|---|---|---|
| Omitted | Applies to all requests. | Preserves the stored rule. |
| null | Applies to all requests. | Clears the stored rule; applies to all requests. |
| Rule object | Stores the rule. | Replaces the stored rule. |
Removing location from the file does not clear a deployed rule. Set it to null to clear the rule. Review the proposed scope before deployment, because clearing a rule broadens the worker to all requests.
Runtime errors and on_failure
An unhandled error that is reached during validation fails validate and the server-side upload check with INTERNAL_SERVER_ERROR. That observed deploy-time behavior blocks the affected deployment; it does not define how every throw statement or request-time failure is handled. Branch on returned values where an error can be handled by worker code.
Last updated: September 22, 2026