Skip to main content
This guide takes a TypeScript handler from a file on your machine to a deployed, invoked function. It covers both contract kinds and both ways to deploy: source files that Alchemy lays over the runtime image, and an OCI image you build yourself. The commands assume a server on localhost:8780 with no auth, as in the Quickstart. With auth enabled, add -H "Authorization: Bearer $TOKEN" to every call.

The Node runtime

Node runs handler.ts directly with its built-in type stripping, so there is no compile step. Write TypeScript whose types can simply be erased, and import local files with their .ts extension. The runtime’s package.json sets "type": "module", so the handler is an ES module. Nothing is installed at build time. A function built from source can import Node’s modules, apache-arrow and its own files under /app. A function that needs other packages ships as an image. ListRuntimes returns the exact runtime image for your server:

The protocol

For each invocation the supervisor starts node /app/handler.ts as a new process, writes the input to stdin and closes it, takes stdout as the output and streams stderr to the invocation’s log. A non-zero exit is a crash, with the exit status and the last 4 KiB of stderr as the error message. An uncaught exception exits non-zero, so it is reported the same way. A JSON Schema contract passes one JSON value each way. An Arrow contract passes one Arrow IPC stream with exactly one record batch each way. See Contracts. Write diagnostics with console.error. console.log writes to stdout, which is the output.

Write a JSON handler

The runtime’s JSON Schema starter reads one value and returns it:
handler.ts
readFileSync(0) reads stdin to the end and writeSync(1, ...) writes stdout before the process exits.

Write an Arrow handler

An Arrow function receives a batch of rows and returns a batch with the same number of rows in the same order. The runtime’s Arrow starter:
handler.ts
examples/embed/typescript/handler.ts is a complete one. It reads id and text columns and returns per row the cleaned text, its token count and a 64-dimension embedding. The contract carries both schemas as serialized Arrow IPC. Build them for the embed example with apache-arrow, in a directory where it is installed (npm install apache-arrow@21.0.0):
schemas.ts
contract.ts
This is how the web UI encodes the schemas from its field editor. Fields are matched by position, name, type and nullability.

Deploy from source

A function built from source names the runtime image and carries its files. The server keeps them in its artifacts bucket and hosts extract them over the image at /app, at most 64 files and 1 MiB in total. The runtime runs handler.ts. Do not send a package.json: it would replace the runtime’s, and nothing is installed.
1

Create the function

protocol is required and INVOCATION_PROTOCOL_EXEC is the only one implemented. Leave timeoutMs, maxConcurrency, retries and resources out to take the defaults: a 30 s timeout, no concurrency limit, 2 retries, 1 vCPU and 128 MiB.
2

Wait for the build

The version starts in BUILDING and turns READY once a host has built and snapshotted it. Only a ready version can be invoked.
Source builds need the server’s ARTIFACTS_BUCKET. Without it, CreateFunction refuses a spec with source.

Deploy as an image

Ship an image when the function needs packages beyond apache-arrow. Build on the runtime so the entrypoint stays node /app/handler.ts. The embed example’s Dockerfile:
Dockerfile
To add packages, copy your own package.json over the runtime’s, keep apache-arrow in it if you use Arrow, and run npm install in the Dockerfile. Then build for the hosts’ architecture and push:
Create the function with that image and no source:
In the web UI, choose Image and enter the reference. The version runs the digest the tag resolved to when it was built. See Deploy any OCI image for private registries.

Invoke it

POST the input to /functions/<function-id>/invoke with the contract’s content type.
The response carries Alchemy-Invocation-Id and Alchemy-Version. A handler that throws answers 500 with the error as JSON, and one past its timeout answers 504. The function’s Invocations tab shows each call with its stderr, and the Workbench tab invokes it from the browser. See HTTP invoke for versions, retries and async calls.

Next steps

Troubleshooting

Read contract violations, crashes, timeouts and build failures.

Runtimes and builds

How a spec becomes a root filesystem and a snapshot.