@fastly/js-compute

JavaScript SDK and CLI for building JavaScript applications on Fastly Compute.

Getting Started

We recommend using the Fastly CLI to create, build, and deploy JavaScript Fastly Compute services, as described on the Fastly Developer Hub.

Detailed documentation for JavaScript Fastly Compute services is also available on Fastly Developer Hub.

Usage

JavaScript Examples

The Fastly Developer Hub has a collection of example JavaScript applications.

Here is a small example application:

/// <reference types="@fastly/js-compute" />

async function app(event) {
    const request = event.request;
    return new Response(`You made a request to ${request.url}`)
}

addEventListener("fetch", event => {
  event.respondWith(app(event));
});

CLI Flags and configuration

The CLI is typically invoked by the build script defined in your project's package.json scripts.

{
  "scripts": {
    "build": "js-compute-runtime src/index.js bin/main.wasm"
  }
}

The CLI is invoked as follows:

js-compute-runtime [OPTIONS] <input-js-file> <output-wasm-file>

Options can be specified on the command line or added to a persistent configuration file for the project. The CLI will search for a configuration starting from the current directory in the following order:

• A fastlycompute property in package.json
• .fastlycomputerc.json
• fastlycompute.config.js

The CLI will search for a configuration starting from the current directory in the following order:

• A fastlycompute property in package.json
• .fastlycomputerc (JSON or YAML)
• .fastlycomputerc.json, .fastlycomputerc.yaml, .fastlycomputerc.yml
• .fastlycomputerc.js, .fastlycomputerc.mjs
• fastlycompute.config.js, fastlycompute.config.mjs

If an option is defined in both the command line and the configuration file, the command line option takes precedence.

Supported Options

| Config Key | CLI Flag | Type | Description | |:----------------------------------------------|:-----------------------------------------------------|:----------------------------|:----------------------------------------------------------------------------------------------------------------------------------------------------------| | enableAOT | --enable-aot | boolean | Enable AOT compilation for performance | | aotCache | --aot-cache | string (path) | Specify a path to the AOT cache file | | enableHttpCache | --enable-http-cache | boolean | Enable the HTTP cache hook API | | enableExperimentalHighResolutionTimeMethods | --enable-experimental-high-resolution-time-methods | boolean | Enable experimental fastly.now() method | | enableExperimentalTopLevelAwait | --enable-experimental-top-level-await | boolean | Enable experimental top level await | | enableStackTraces | --enable-stack-traces | boolean | Enable stack traces | | excludeSources | --exclude-sources | boolean | Don't include sources in stack traces | | debugIntermediateFiles | --debug-intermediate-files | string (path) | Output intermediate files in directory | | debugBuild | --debug-build | boolean | Use debug build of the SDK runtime | | engineWasm | --engine-wasm | string (path) | Specify a custom Wasm engine (advanced) | | wevalBin | --weval-bin | string (path) | Specify a custom weval binary (advanced) | | env | --env | string \| object \| array | Set environment variables, possibly inheriting from the current environment. Multiple variables can be comma-separated (e.g., --env ENV_VAR,OVERRIDE=val) |

NOTE: The env field is additive. Values defined on the command-line values append to, rather than replace, the values defined in any configuration file.

Example command-line options

js-compute-runtime --enable-aot --enable-stack-traces --enable-top-level-await --env=LOG_LEVEL=debug ./src/index.js ./bin/main.wasm

Example .fastlycomputerc.json

{
  "enableAOT": true,
  "enableStackTraces": true,
  "enableTopLevelAwait": true,
  "env": {
    "LOG_LEVEL": "debug"
  }
}

Example package.json

{
  "name": "my-fastly-service",
  "type": "module",
  "dependencies": {
    "@fastly/cli": "^13.0.0"
  },
  "scripts": {
    "build": "js-compute-runtime ./src/index.js ./bin/main.wasm",
    "dev": "fastly compute serve",
    "deploy": "fastly compute publish"
  },
  "fastlycompute": {
    "enableAOT": true,
    "enableStackTraces": true,
    "enableTopLevelAwait": true,
    "env": {
      "LOG_LEVEL": "debug"
    }
  }
}

API documentation

The API documentation for the JavaScript SDK is located at https://js-compute-reference-docs.edgecompute.app.

Security

If you find any security issues, see the Fastly Security Reporting Page or send an email to: [email protected]

We plan to disclose any found security vulnerabilities per the GitHub security vulnerability guidance. Note that communications related to security issues in Fastly-maintained OSS as described here are distinct from Fastly security advisories.

Changelog

The changelog can be found here.

License

Apache-2.0 WITH LLVM-exception