nexus
AdaptersNode IPC

Overview

Configure and operate Nexus local daemon and client IPC.

@nexus-js/node-ipc connects local daemon and client processes through filesystem Unix domain sockets. Use it when one long-lived local process exposes Nexus services and one or more local clients call those services.

This section covers the adapter-specific behavior. For authorization hooks shared by all adapters, read Authorization and policy.

Start Here

Package Routing

  • Foundation runtime: @nexus-js/core
  • Local IPC adapter: @nexus-js/node-ipc

Install both in daemon and client packages:

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

When To Use It

Use node-ipc when your application has:

  • one local daemon process that owns services
  • one or more local clients, such as CLIs or helper processes
  • same-machine communication only
  • a Unix socket path that can represent the daemon instance

Do not use it for browser contexts, cross-machine networking, or long-lived handles that must survive daemon restarts without being recreated.

What The Adapter Provides

  • daemon and client factory helpers
  • default socket address resolution
  • custom address resolvers
  • filesystem Unix socket server and client endpoints
  • binary packet framing over socket streams
  • optional shared-secret pre-auth
  • runtime directory and stale socket safety checks
  • node-ipc endpoint and connection metadata, exact targets, and address helpers

What Core Still Owns

The adapter does not replace core Nexus behavior.

Core still owns:

  • tokens and service contracts
  • service exposure
  • proxy creation
  • target resolution
  • logical connection handshake
  • policy.canConnect and policy.canCall
  • resource reference lifecycle
  • session-bound proxy semantics

Runtime Scope

The current verification boundary is Node on Linux and Unix-like systems using filesystem Unix domain sockets. Bun has no verified repository CI coverage; this documentation makes no support or non-support claim. See Runtime compatibility for the boundary.

Testing Boundary

Use @nexus-js/testing and createMockNexus() for unit tests of application code that consumes daemon services through a NexusInstance.

Do not use the mock to validate node-ipc adapter behavior. It does not exercise Unix socket addressing, filesystem permissions, packet framing, shared-secret pre-auth, stale socket cleanup, daemon close/recreate behavior, or real disconnect timing.

Use Testing for adapter and real socket integration testing guidance.

Transport Limits

Node IPC uses binary packets. Daemon and client helpers accept a transport option for frame, message, and aggregate framework-buffer limits; defaults are 64 KiB, 16 MiB, and 64 MiB:

usingNodeIpcDaemon({
  appId: "example-app",
  transport: {
    maxFrameBytes: 64 * 1024,
    maxMessageBytes: 16 * 1024 * 1024,
    maxBufferedBytes: 64 * 1024 * 1024,
  },
});

The configured frame limit cannot exceed the IPC framing packet limit.

Edit this page on GitHub