@voxalsh/sdk

The library you build voxal apps against. voxal runs interactive terminal apps that anyone can reach over SSH: you write a small JavaScript app, deploy it with the voxal CLI, and from then on anyone can run it with ssh [email protected].

Full documentation: docs.voxal.sh.

The package has two layers, and you import whichever fits your app:

• Core (@voxalsh/sdk): handle connection and input events and write to the terminal yourself. Zero runtime dependencies.
• UI (@voxalsh/sdk/ui): build the interface with React and flexbox, mirroring Ink one to one.

Install

The fastest way to start is the project initializer, which scaffolds an app and adds the SDK for you:

npm create voxal-app my-app

To add it to an existing project:

npm install @voxalsh/sdk

The CLI bundles the SDK into your app at deploy time, so there is nothing to build.

Core quick start

A complete app is createApp(), a few handlers, and .listen().

import { createApp, fetch } from '@voxalsh/sdk';

createApp()
  .onConnect((conn) => {
    conn.write('\x1b[2J\x1b[H');                       // clear screen, cursor home
    conn.write(`hello, your terminal is ${conn.cols}x${conn.rows}\r\n`);
    conn.write('[c] cat fact   [q] quit\r\n');
  })
  .onKey(async (conn, data) => {
    if (data === 'q' || data === '\x03') return conn.close();  // q or Ctrl-C
    if (data === 'c') {
      try {
        const res = await fetch('https://catfact.ninja/fact');
        conn.write('🐱 ' + JSON.parse(res.body).fact + '\r\n');
      } catch (err) {
        conn.write('(fetch failed: ' + err.message + ')\r\n');
      }
    }
  })
  .onClose(() => { /* per-session cleanup */ })
  .listen();

One app instance serves every connected user, each with their own conn. Keep per-session state keyed by conn.id and free it in onClose. See the SDK reference for the full surface.

What you get

• createApp() returns a chainable app. Register onConnect, onKey, onResize, and onClose handlers, then call .listen() once.
• conn is one terminal session: conn.id, conn.cols, conn.rows, conn.write(str), and conn.close().
• fetch(url, opts?) makes a guarded HTTP request and returns { status, headers, body }. Your app has no network of its own, so this runs the request safely on your behalf. See the fetch reference.
• env(key) reads an app secret (e.g. an API key). Set values with voxal env set KEY value; they are encrypted (sealed to the box, never in your bundle, never readable by the dashboard) and injected into your app at boot. Returns the string, or undefined if unset; call env() with no argument for a frozen object of all secrets.

UI quick start

import React, { useState } from 'react';
import { serve, Box, Text, useInput, useApp } from '@voxalsh/sdk/ui';

function Counter() {
  const [n, setN] = useState(0);
  const { exit } = useApp();
  useInput((input, key) => {
    if (input === 'q') exit();
    if (key.upArrow) setN((c) => c + 1);
    if (key.downArrow) setN((c) => c - 1);
  });
  return (
    <Box borderStyle="round" padding={1} flexDirection="column">
      <Text>count: <Text bold color="green">{n}</Text></Text>
      <Text dimColor>up and down to change, q to quit</Text>
    </Box>
  );
}

serve(() => <Counter />);

serve() gives every connection its own React tree. react is a peer dependency, so add it to your app (npm install react). The UI layer mirrors Ink, so the components (<Box>, <Text>, <Static>, and more) and hooks (useInput, useApp, useFocus, useWindowSize, and more) match what you already know. See the UI reference.

License

MIT