serve and render

The UI layer has two entry points. serve is the normal one and wires up the whole app. render is lower level and hands you a single mounted instance you drive yourself. Both take the same options.

serve

serve(factory: (conn) => ReactElement, options?: RenderOptions): App

serve is the entry point most apps use. factory is called once per SSH connection and returns the React element for that session. Each connection gets its own React tree and is isolated from the others. serve wires keyboard input, resize, and close for you, and closes the connection when the app exits (for example when a component calls useApp().exit()). It returns the running app.

import { serve, Box, Text } from '@voxalsh/sdk/ui';

function App({ id }) {
  return (
    <Box borderStyle="round" padding={1}>
      <Text>hello, your connection id is <Text bold>{id}</Text></Text>
    </Box>
  );
}

serve((conn) => <App id={conn.id} />);

Pass the connection through factory when a component needs its id or initial size. For live size that updates on resize, use useWindowSize inside the tree instead.

Fullscreen

serve(() => <App />, { fullscreen: true });

Fullscreen uses the terminal's alternate screen and a cell diff renderer, so your UI owns the whole viewport and the user's scrollback is restored on exit. Without it, the UI renders inline and grows the terminal as needed.

render

render(node: ReactElement, conn, options?: RenderOptions): Instance

render mounts one element on one connection and returns an instance handle. Unlike serve, it does not wire input or resize. You forward those yourself, which is what you want when you are embedding a UI inside an app that already manages its own connection lifecycle with the core SDK.

import { createApp } from '@voxalsh/sdk';
import { render } from '@voxalsh/sdk/ui';
import { App } from './App.jsx';

const instances = new Map();

createApp()
  .onConnect((conn) => instances.set(conn.id, render(<App />, conn)))
  .onKey((conn, data) => instances.get(conn.id)?.handleData(data))
  .onResize((conn) => instances.get(conn.id)?.resize())
  .onClose((conn) => {
    instances.get(conn.id)?.unmount();
    instances.delete(conn.id);
  })
  .listen();

The instance handle

render returns an object with these methods.

Most apps should use serve, which calls all of this for you.

RenderOptions

The options object is shared by serve and render.