nexus
AdaptersNode IPC

Quick Start

Set up a Nexus daemon and client over local Unix sockets.

Configure a daemon that exposes an echo service, then call it from a client process.

1. Install Packages

pnpm add @nexus-js/core @nexus-js/node-ipc

Authentication is optional

The quick start uses the default local socket setup without a shared secret. Add the adapter’s pre-auth configuration before exposing services when local clients are not already trusted.

2. Start From A Shared Contract

Both processes import EchoToken from shared code using the shared contract pattern. Its service exposes echo(input: string): Promise<string>.

3. Configure The Daemon

The daemon owns the listening endpoint and service implementation.

import { usingNodeIpcDaemon } from "@nexus-js/node-ipc";
import { EchoToken } from "./shared";

usingNodeIpcDaemon({ appId: "example-app" }).provide(EchoToken, {
  async echo(input) {
    return `echo:${input}`;
  },
});

The daemon’s peer identity is NodeIpcContextMeta; the client connects with an exact NodeIpcConnectionTarget containing appId and optional instance.

4. Configure The Client

The client owns an outgoing endpoint. Connect with the daemon’s exact address.

import { nexus } from "@nexus-js/core";
import { usingNodeIpcClient } from "@nexus-js/node-ipc";
import { EchoToken } from "./shared";

usingNodeIpcClient({
  appId: "example-app",
});

const connection = await nexus.connect({
  target: { context: "node-ipc-daemon", appId: "example-app" },
});
const echo = connection.get(EchoToken);

console.log(await echo.echo("hello"));

Pass timeout to bound acquisition and callTimeout to get to override the runtime call default:

const connection = await nexus.connect({
  target: {
    context: "node-ipc-daemon",
    appId: "example-app",
  },
  timeout: 30_000,
});
const echo = connection.get(EchoToken, { callTimeout: 5_000 });

Optional Workflows

First Failure Checklist

If the first call fails, check these in order:

  1. Is the daemon process still running?
  2. Are daemon and client using the same appId and instance?
  3. Does the socket path resolve where you expect? See Addressing.
  4. If authToken is configured, do both sides use the same non-empty token?
  5. Does policy.canConnect allow the client?
  6. Does policy.canCall allow the service name and operation?
  7. Are you reusing an old proxy after daemon restart? Reconnect and get a fresh proxy.
Edit this page on GitHub