@inkly/node

The Node.js reference adapter for inkly — a small ws-based bridge from Node's HTTP upgrade event to @inkly/core's adapter handlers.

This is the adapter shape other runtimes mirror. Use serve() for a standalone server or attachInkly() when an existing HTTP framework already owns the port.

Why it exists

@inkly/node keeps Node-specific socket handling out of your app: it negotiates the inkly.v1 subprotocol, normalizes IncomingMessage into an inkly upgrade request, optionally pre-authorizes at HTTP upgrade time, and forwards messages into app.handlers. Because this adapter is the reference implementation, Bun, Deno, Cloudflare, and framework adapters can mirror the same serve(app, opts) / attachInkly(server, app, opts) shape.

Install

pnpm add @inkly/node @inkly/core zod

Quickstart

import { inkly, contract } from "@inkly/core";
import { serve } from "@inkly/node";
import { z } from "zod";

const api = contract({
  actions: {
    echo: { input: z.object({ msg: z.string() }), output: z.object({ msg: z.string(), user: z.string() }) },
  },
  events: {},
  streams: {},
});

const app = inkly(api, {
  async authorize(_request, params) {
    const token = (params as { token?: string } | undefined)?.token;
    if (token !== "demo-token") throw new inkly.Unauthorized("bad token");
    return { user: "daryl" };
  },
});

app.defineAction("echo", (peer, input) => ({ msg: input.msg, user: peer.context.user }));

const handle = serve(app, { port: 3000, path: "/ws" });
console.log(`inkly listening on ${handle.port}`);

API reference

| API | Purpose | | --- | --- | | serve(app, { port?, server?, host?, path?, authorize?, compression?, ws? }) | Starts a standalone Node server when port is provided, or embeds into an existing http.Server when server is provided. | | ServeHandle.server | The Node HTTP server. | | ServeHandle.wss | The underlying ws WebSocketServer. | | ServeHandle.port | Bound port getter; null until listening. | | ServeHandle.close() | Closes clients, detaches the adapter, and stops the owned server. | | attachInkly(server, app, opts) | Low-level upgrade interceptor for sharing a port with another HTTP framework. | | AttachHandle.wss | The underlying ws WebSocketServer. | | AttachHandle.detach() | Removes the upgrade listener and closes the WebSocketServer. | | opts.path | Only handles upgrades for this path; defaults to /. | | opts.authorize(request) | Pre-authorizes at HTTP upgrade time; throw an inkly error to control rejection status, otherwise rejection is 401. | | opts.compression | Enables permessage-deflate (RFC 7692). Shorthand for ws: { perMessageDeflate: true }; an explicit ws.perMessageDeflate wins. Off by default (it trades CPU for bandwidth). | | opts.ws | Extra ws server options such as maxPayload or perMessageDeflate. |

Docs

• docs/overview.md — adapter responsibilities and handles.
• docs/embedding.md — serve() vs attachInkly() and sharing a port.
• docs/auth-at-upgrade.md — HTTP upgrade pre-auth.

Examples

• examples/standalone.ts — serve an app on a port.
• examples/attach-to-http-server.ts — attach to an existing node:http server.

License

Dazza Public License 1.0 (LicenseRef-Dazza-1.0).