jam

Jam is a self-hosted JavaScript worker runtime. It runs ECMAScript modules with worker-style Web APIs such as Request, Response, URL, streams, timers, and fetch, and it uses jam.json to connect services and bindings to worker modules on infrastructure you control.

This package is the cross-platform npm entrypoint. It installs the small Node.js jam launcher, resolves the matching jam-<platform>-<arch> optional dependency for your host, forwards CLI arguments to the native Jam runtime binary, and publishes the public TypeScript declarations for Jam worker APIs.

Use this package to try Jam quickly (npx jam) and to pull in TypeScript declarations. For production and other long-lived servers, install the native binary from GitHub Releases and run it directly — see Installing Jam.

Install

Run Jam without adding it to package.json:

npx jam

Or install it in a project (also pulls in the public TypeScript declarations):

npm install jam
npx jam --help

Quick Start

Create a worker module:

export async function http(request, context) {
    const url = new URL(request.url);
    return new Response(`hello from ${url.pathname}\n`, {
      headers: { "content-type": "text/plain; charset=utf-8" },
    });
  }

Create jam.json:

{
  "services": {
    "api": {
      "listen": "http://:8787",
      "action": "./worker.js"
    }
  }
}

Serve it locally:

npx jam

Jam listens on 127.0.0.1:8787 by default:

curl http://127.0.0.1:8787/hello

TypeScript

The jam package includes TypeScript declarations for Jam worker APIs, loader hooks, execution context, event payloads, and configured binding facades:

import type { HttpHandler } from "jam";

interface Env {
  readonly APP_NAME: string;
}

export const http: HttpHandler<Env> = (_request, context) => {
  return new Response(context.env.APP_NAME);
};

If your project uses Jam's global worker APIs without importing from jam, add jam to compilerOptions.types:

{
  "compilerOptions": {
    "types": ["jam"]
  }
}

The same applies to .jam template imports (import page from "./home.jam"): the package ships an ambient declare module "*.jam" declaration that loads whenever the jam types do, so it is available automatically once any file imports from jam, or whenever jam is in compilerOptions.types.

Imported templates use one required input object containing their declared props plus request, response, and context. The jam/templates export provides createTemplateInput(props, options?) and createTemplateResponse(init?) for deterministic tests and standalone rendering.

Global worker APIs

Loading Jam's types also declares the globals Jam installs at runtime — Request, Response, Headers, fetch, the Web Streams, URL, URLPattern, Blob, File, FormData, TextEncoder/TextDecoder, AbortController, the Event family, WebSocket, CompressionStream, Web Crypto (crypto, SubtleCrypto, CryptoKey), structuredClone, queueMicrotask, timers, and console. These are declared with Jam's own runtime shapes rather than borrowed from TypeScript's dom library, so importing jam does not inject the browser DOM. Browser-only globals such as window, document, localStorage, and caches are absent at the type level, matching their absence at runtime.

Because Jam supplies these globals itself, worker code should compile with the ECMAScript libraries only — do not add dom or dom.iterable to compilerOptions.lib, and do not mix Jam's worker globals with the browser DOM in a single compilation. A project that also builds browser code should type-check that code in a separate compilation (its own tsconfig.json) that includes dom and does not load jam.

Node builtin module declarations are supplied by the official @types/node package, not by Jam. Install @types/node separately when application code imports supported explicit node: modules. Jam's Web globals coexist with @types/node in the same compilation — keep compilerOptions.skipLibCheck at its usual true when combining the two, as @types/node itself recommends. Note that @types/node also declares globals Jam does not install at runtime (for example a global Buffer value): construct a buffer with import { Buffer } from "node:buffer" rather than relying on the bare Buffer global.

Supported Runtime Packages

The jam launcher selects one of these runtime packages automatically:

• jam-linux-x64
• jam-linux-arm64
• jam-darwin-x64
• jam-darwin-arm64
• jam-win32-x64

The Linux packages are glibc builds; musl-based distributions such as Alpine are not supported. If the current platform is unsupported or the selected optional dependency is missing, the launcher prints a deterministic error and exits non-zero.