Note:

HeliumTS is under active development. Expect bugs and breaking changes. If you find any issues, please report them in our GitHub

A stable release is planned for early 2026.

RPC (Remote Procedure Calls)

Define server-side functions using defineMethod and call them from the client using useCall or useFetch.

Server

src/server/tasks.ts

1import { defineMethod } from "heliumts/server";
2
3// Getting tasks
4export const getTasks = defineMethod(async (args: { status: string }) => {
5    // Add your own database logic here
6    return [{ id: 1, name: "Task 1", status: args.status }];
7});
8
9// Creating a new task
10export const createTask = defineMethod(async (args: { name: string }) => {
11    // Add your own create task logic
12    return { id: 2, name: args.name };
13});

Client

src/pages/tasks.tsx

1import { useFetch, useCall } from "heliumts/client";
2import { getTasks, createTask } from "heliumts/server";
3
4export default function TasksPage() {
5    // Fetch data (auto-runs on mount)
6    // Data is typed based on server method return type
7    const { data, isLoading } = useFetch(getTasks, { status: "open" });
8
9    // Mutation (callable function)
10    // The call function is typed based on server method args and return type
11    const { call: add, isCalling } = useCall(createTask, {
12        invalidate: [getTasks] // Auto-refresh getTasks after success everywhere it's used
13    });
14
15    return (
16        <div>
17            <button onClick={() => add({ name: "New Task" })}>
18                {isCalling ? "Adding..." : "Add Task"}
19            </button>
20            {data?.map(task => <div key={task.id}>{task.name}</div>)}
21        </div>
22    );
23}

Public errors in production

In production, server errors are redacted to a generic Server error message by default. If you want to expose a safe message to clients, throw aPublicError or an error-like object with { public: true } from your RPC method.

1import { defineMethod, PublicError } from "heliumts/server";
2
3export const createTask = defineMethod(async (args) => {
4    if (!args.name?.trim()) {
5        throw new PublicError("Task name is required");
6        // Or: throw { public: true, message: "Task name is required" };
7    }
8
9    return createTaskInDb(args);
10});