@fastly/js-compute
Version:
JavaScript SDK and CLI for building JavaScript applications on [Fastly Compute](https://www.fastly.com/products/edge-compute/serverless).
151 lines (110 loc) • 8.5 kB
Markdown
# /js-compute
JavaScript SDK and CLI for building JavaScript applications on [Fastly Compute](https://www.fastly.com/products/edge-compute/serverless).
 
## Getting Started
We recommend using the [Fastly CLI](https://github.com/fastly/cli) to create, build, and deploy JavaScript Fastly Compute services, as [described on the Fastly Developer Hub](https://developer.fastly.com/learning/compute/).
[Detailed documentation for JavaScript Fastly Compute services](https://developer.fastly.com/learning/compute/javascript/) is also available on Fastly Developer Hub.
## Usage
### JavaScript Examples
The Fastly Developer Hub has a collection of [example JavaScript applications](https://developer.fastly.com/solutions/examples/javascript/).
Here is a small example application:
```js
/// <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.
```json
{
"scripts": {
"build": "js-compute-runtime src/index.js bin/main.wasm"
}
}
```
The CLI is invoked as follows:
```sh
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`
<details>
<summary>Click here to see full list</summary>
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`
</details>
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](https://www.fastly.com/documentation/guides/concepts/cache/#modifying-a-request-as-it-is-forwarded-to-a-backend) |
| `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
```sh
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`
```json
{
"enableAOT": true,
"enableStackTraces": true,
"enableTopLevelAwait": true,
"env": {
"LOG_LEVEL": "debug"
}
}
```
#### Example `package.json`
```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](https://js-compute-reference-docs.edgecompute.app).
## Security
If you find any security issues, see the [Fastly Security Reporting Page](https://www.fastly.com/security/report-security-issue) or send an email to: `security@fastly.com`
We plan to disclose any found security vulnerabilities per the [GitHub security vulnerability guidance](https://docs.github.com/en/code-security/security-advisories/guidance-on-reporting-and-writing/about-coordinated-disclosure-of-security-vulnerabilities#best-practices-for-maintainers). Note that communications related to security issues in Fastly-maintained OSS as described here are distinct from [Fastly security advisories](https://www.fastly.com/security-advisories).
## Changelog
The changelog can be found [here](https://github.com/fastly/js-compute-runtime/blob/main/CHANGELOG.md).
## License
[Apache-2.0 WITH LLVM-exception](./LICENSE)