Building Spin Components in JavaScript
- Installing Templates
- Structure of a JS/TS Component
- Building and Running the Template
- HTTP Components
- Sending Outbound HTTP Requests
- Storing Data in Redis From JS/TS Components
- Routing in a Component
- Storing Data in the Spin Key-Value Store
- Storing Data in SQLite
- Storing Data in MySQL and PostgreSQL Relational Databases
- AI Inferencing From JS/TS Components
- Node.js Compatibility
- Using External NPM Libraries
- Caveats
With JavaScript being a very popular language, Spin provides an SDK to support building components. The development of the JavaScript SDK is continually being worked on to improve user experience and add features. The SDK is based on ComponentizeJS
.
This guide assumes you have Spin installed. If this is your first encounter with Spin, please see the Quick Start, which includes information about installing Spin with the JavaScript templates and creating JavaScript and TypeScript applications.
This guide assumes you are familiar with the JavaScript programming language, but if you are just getting started, be sure to check the MDN guide.
All examples from this page can be found in the JavaScript SDK repository on GitHub.
Want to go straight to the Spin SDK reference documentation? Find it here.
Installing Templates
The JavaScript/TypeScript templates can be installed from spin-js-sdk repository using the following command:
$ spin templates install --git https://github.com/fermyon/spin-js-sdk --update
which will install the http-js
and http-ts
templates:
Copying remote template source
Installing template http-ts...
Installing template http-js...
Installed 2 template(s)
+-------------------------------------------------+
| Name Description |
+=================================================+
| http-js HTTP request handler using Javascript |
| http-ts HTTP request handler using Typescript |
+-------------------------------------------------+
Structure of a JS/TS Component
A new JS/TS component can be created using the following command:
$ spin new -t http-ts hello-world --accept-defaults
This creates a directory of the following structure:
hello-world/
├── knitwit.json
├── package.json
├── spin.toml
├── src
│ ├── index.ts
│ └── spin.ts
├── tsconfig.json
└── webpack.config.js
The source for the component is present in src/index.ts
. Webpack is used to bundle the component into a single .js
file which will then be compiled to a .wasm
module.
Going from JavaScript to Wasm
The JS source is compiled to a wasm
module using the j2w
node executable provided by the @fermyon/spin-sdk
which is a wrapper around ComponentizeJS
. The knitwit.json
is the configuration file used by knitwit to manage the WebAssembly dependencies of each package.
Building and Running the Template
First, the dependencies for the template need to be installed using the following commands:
$ cd hello-world
$ npm install
Next step is to use the spin build
command to run the build script for the component. Once a Spin compatible module is created, it can be run using spin up
:
$ spin build
$ spin up
spin build
will execute the command in the command
key under the [component.<component-name>.build]
section from spin.toml
for each component in your application. In this case an npm
script will be run. The command in the package.json
will looks something like:
"scripts": {
"build": "npx webpack --mode=production && npx mkdirp target && npx j2w -i dist.js -d combined-wit -n combined -o target/hello-world.wasm",
"test": "echo \"Error: no test specified\" && exit 1"
}
HTTP Components
In Spin, HTTP components are triggered by the occurrence of an HTTP request, and must return an HTTP response at the end of their execution. Components can be built in any language that compiles to WASI, and Javascript/TypeScript has improved support for writing Spin components with the Spin JS/TS SDK.
Make sure to read the page describing the HTTP trigger for more details about building HTTP applications.
Building a Spin HTTP component using the JS/TS SDK means writing a single function that takes an HTTP request and a Response Builder which can be used to return an HTTP response as a parameter.
Below is a complete implementation for such a component in TypeScript:
import { ResponseBuilder } from "@fermyon/spin-sdk";
export async function handler(req: Request, res: ResponseBuilder) {
console.log(req);
res.send("hello universe");
}
The important things to note in the implementation above:
- The
handler
function is the entry point for the Spin component. - The execution of the function terminates once
res.send
orres.end
is called.
Sending Outbound HTTP Requests
If allowed, Spin components can send outbound HTTP requests. Let’s see an example of a component that makes a request to an API that returns random animal facts
import { ResponseBuilder } from "@fermyon/spin-sdk";
interface AnimalFact {
timestamp: number;
fact: string;
}
export async function handler(req: Request, res: ResponseBuilder) {
const animalFactResponse = await fetch("https://random-data-api.fermyon.app/animals/json")
const animalFact = await animalFactResponse.json() as AnimalFact
const body = `Here's an animal fact: ${animalFact.fact}\n`
res.set({"content-type": "text/plain"})
res.send(body)
}
Before we can execute this component, we need to add the random-data-api.fermyon.app
domain to the application manifest allowed_outbound_hosts
list containing the list of
domains the component is allowed to make HTTP requests to:
spin_manifest_version = 2
[application]
authors = ["Your Name <your-name@example.com>"]
description = ""
name = "hello-world"
version = "0.1.0"
[[trigger.http]]
route = "/..."
component = "hello-world"
[component.hello-world]
source = "target/hello-world.wasm"
exclude_files = ["**/node_modules"]
allowed_outbound_hosts = ["https://random-data-api.fermyon.app"]
[component.hello-world.build]
command = "npm run build"
The component can be built using the spin build
command. Running the application using spin up
will start the HTTP listener locally (by default on localhost:3000
):
$ curl -i localhost:3000
HTTP/1.1 200 OK
date = "2023-11-04T00:00:01Z"
content-type: application/json; charset=utf-8
content-length: 185
server: spin/0.1.0
Here's an animal fact: Reindeer grow new antlers every year
Without the
allowed_outbound_hosts
field populated properly inspin.toml
, the component would not be allowed to send HTTP requests, and sending the request would result in a “Destination not allowed” error.
You can set
allowed_outbound_hosts = ["https://*:*"]
if you want to allow the component to make requests to any HTTP host. This is not recommended unless you have a specific need to contact arbitrary servers and perform your own safety checks.
We just built a WebAssembly component that sends an HTTP request to another service, manipulates that result, then responds to the original request. This can be the basis for building components that communicate with external databases or storage accounts, or even more specialized components like HTTP proxies or URL shorteners.
Storing Data in Redis From JS/TS Components
You can find a complete example for using outbound Redis from an HTTP component in the spin-js-sdk repository on GitHub.
Using the Spin’s JS SDK, you can use the Redis key/value store and to publish messages to Redis channels.
Let’s see how we can use the JS/TS SDK to connect to Redis:
import { ResponseBuilder, Redis } from '@fermyon/spin-sdk';
const encoder = new TextEncoder();
const decoder = new TextDecoder();
const redisAddress = 'redis://localhost:6379/';
export async function handler(_req: Request, res: ResponseBuilder) {
try {
let db = Redis.open(redisAddress);
db.set('test', encoder.encode('Hello world'));
let val = db.get('test');
if (!val) {
res.status(404);
res.send();
return;
}
// publish to a channel names "message"
db.publish("message", val)
res.send(val);
} catch (e: any) {
res.status(500);
res.send(`Error: ${JSON.stringify(e.payload)}`);
}
}
This HTTP component demonstrates fetching a value from Redis by key, setting a key with a value, and publishing a message to a Redis channel.
When using Redis databases hosted on the internet (i.e) not on localhost, the
redisAddress
must be of the format “redis://<USERNAME>:<PASSWORD>@<REDIS_URL>” (e.g)redis://myUsername:myPassword@redis-database.com
As with all networking APIs, you must grant access to Redis hosts via the allowed_outbound_hosts
field in the application manifest:
[component.storage-demo]
allowed_outbound_hosts = ["redis://localhost:6379"]
Routing in a Component
The JavaScript/TypeScript SDK provides a router that makes it easier to handle routing within a component. The router is based on itty-router
. An additional function handleRequest
has been implemented in the router to allow passing in the Spin HTTP request directly. An example usage of the router is given below:
import { ResponseBuilder, Router } from '@fermyon/spin-sdk';
let router = Router();
router.get("/", (_, req, res) => { handleDefaultRoute(req, res) })
router.get("/home/:id", (metadata, req, res) => { handleHomeRoute(req, res, metadata.params.id) })
async function handleDefaultRoute(_req: Request, res: ResponseBuilder) {
res.set({ "content-type": "text/plain" });
res.send("Hello from default route");
}
async function handleHomeRoute(_req: Request, res: ResponseBuilder, id: string) {
res.set({ "content-type": "text/plain" });
res.send(`Hello from home route with id: ${id}`);
}
export async function handler(req: Request, res: ResponseBuilder) {
await router.handleRequest(req, res);
}
Storing Data in the Spin Key-Value Store
Spin has a key-value store built in. For information about using it from TypeScript/JavaScript, see the key-value store tutorial.
Storing Data in SQLite
For more information about using SQLite from TypeScript/Javascript, see SQLite storage.
Storing Data in MySQL and PostgreSQL Relational Databases
For more information about using relational databases from TypeScript/JavaScript, see Relational Databases.
AI Inferencing From JS/TS Components
For more information about using Serverless AI from JS/TS, see the Serverless AI API guide.
Node.js Compatibility
The SDK does not support the full specification of Node.js
. A limited set of APIs can be polyfilled using the @fermyon/wasi-ext
library which provides a webpack plugin. It can be used by installing the library first using:
$ npm install @fermyon/wasi-ext
Once installed, the plugin provided by it can be added to the webpack config:
const WasiExtPlugin = require("wasi-ext/plugin")
module.exports = {
...
plugins: [
new WasiExtPlugin()
],
...
};
This library only currently supports the following polyfills:
Node.js
buffersprocess
- certain methods are no-ops and few throw exceptions. For detailed list refer to the upstream library. Note:process.env
is populated only inside the handler and returns an empty object outside the handler.fs
- only implementsreadFileSync
andreaddirSync
.os
- Implements onlyEOL
andarch
.
Using External NPM Libraries
Not all the NPM packages are guaranteed to work with the SDK as it is not fully compatible with the browser or
Node.js
. It implements only a subset of the API.
Some NPM packages can be installed and used in the component. If a popular library does not work, please open an issue/feature request in the spin-js-sdk repository.
Suggested Libraries for Common Tasks
These are some of the suggested libraries that have been tested and confirmed to work with the SDK for common tasks.
Caveats
- All
spin-sdk
related functions and methods (likeVariables
,Redis
,Mysql
,Pg
,Kv
andSqlite
) can be called only inside thehandler
function. This includesfetch
. Any attempts to use it outside the function will lead to an error. This is due to Wizer using only Wasmtime to execute the script at build time, which does not include any Spin SDK support. - No crypto operation that involve handling private keys are supported.