Skip to content

Runtime and state

Your executor and configurator code runs in Adapt’s serverless JavaScript runtime, with Node.js 24 compatibility. The emulator uses the same runtime. Your tests and build tools run in your local Node.js instead, so they cannot prove that code works in Adapt.

Adapt runs from one to thousands of instances of your program, and replaces them at any time. Each invocation of a handler can run on a different instance.

  • Keep state in stores, not in module variables. Use module variables only for caches.
  • Use the network, timers, and randomness only inside handlers, not when the module loads.
  • Await your work before the handler returns. For work after the response, use ctx.waitUntil().
  • Do not keep sockets or streams for a later invocation.

Most Node.js 24 APIs work, with these limits:

Area Support
Network HTTP, HTTPS, TCP, TLS, and WebSockets. DNS lookup() only.
Files No real file system. node:fs has a small virtual storage, and its /tmp lasts one invocation.
Processes No subprocesses, worker threads, native addons, or node:sqlite.
Protocols node:http2 and node:dgram are only stubs. Use the native modules below.
Crypto Most operations work. Some algorithms are missing.

An import that works does not prove that every operation works. Test in the emulator.

  • Call APIs with credentials through your services.
  • Use fetch or Node’s HTTP modules for other HTTP calls.
  • For streaming HTTP, raw TCP, and QUIC datagrams, use the native modules:
import { http } from "mb:http";
import { connect } from "mb:connect";
import { datagram } from "mb:datagram";

Outbound connections reach public addresses only.

The runtime blocks eval(), new Function(), and other ways to compile code from strings while your handlers run. Do not use them, and check that your libraries do not need them. Build tools and static rendering, which run in your local Node.js, are not affected.

Store Scope
api.getLocalStore("vertex") One vertex instance.
api.getLocalStore("plugin") All vertex instances of your application.
api.getSessionStore("vertex") One vertex in one session fork. Executors only.
api.getSessionStore("plugin") The whole session. Executors only.

Executors get separate local stores for each version of your application.

const store = api.getLocalStore("vertex");
// Keep a value for 15 minutes. The time to live is in seconds.
await store.insert("last_booking", { at: new Date().toISOString() }, 900);
// Missing keys give undefined.
const entry = await store.get<{ at: string }>("last_booking");
// Let one invocation at a time run this section. By default, the lock expires after 5 seconds.
await store.lock("bookings", async () => {
// Check, then write.
});

Stored data is not validated for you. Check what you read, and plan for data saved by older versions. See State.

  • api.readFile() reads the files that your application packages, such as its pages’ HTML.
  • FileForge, Adapt’s document service, is built into the API. It converts HTML, Markdown, and Office files to PDF, merges, splits, and encrypts PDFs, and transforms images. See htmlToPdf, mergePdfs, and the other methods in the SDK.

Each program in runtime.json limits its memory, and the CPU time and wall time of each invocation. See Programs, and measure your use in the emulator.