TypeScript Client

The @pyrpc/client package provides a lightweight, framework-agnostic runtime for calling your RPC procedures. Combined with generated Typed Contracts, it provides a first-class developer experience with zero boilerplate.

1. Install

npm install @pyrpc/client

The install triggers a postinstall script that prompts for your server URL, fetches the introspection schema from GET /rpc, and generates typed contracts into node_modules/@pyrpc/types/src/index.ts.

For non-interactive environments (CI), set PYRPC_URL:

PYRPC_URL=https://api.example.com npm install @pyrpc/client

If you need to regenerate types later (e.g. after adding procedures), re-run the same command or pass PYRPC_URL again.

2. Create the Client

Use the createClient<Types>() factory to initialize your typed client.

import { createClient } from "@pyrpc/client"
import type { Types } from "@pyrpc/types"

// Option 1: Automatic (defaults to current host in browser)
export const client = createClient<Types>();

// Option 2: Explicit (required for Node.js / SSR)
export const client = createClient<Types>({
  baseUrl: "https://api.example.com"
});

[!TIP] If baseUrl is omitted, pyRPC will automatically use window.location.origin. In Server-Side environments (like Next.js Server Components), you must provide an explicit URL.

3. Call Procedures

Procedures are available as async methods with full autocompletion and type validation.

// Inside a React component or Server Action
const user = await client.get_user({ id: 1 });
console.log(user.name); // Typed as string!

Error Handling

The client throws PyRPCError for structured server-side errors.

import { PyRPCError } from "@pyrpc/client";

try {
  const result = await client.add(10, 20);
} catch (e) {
  if (e instanceof PyRPCError) {
    console.error(`Error ${e.code}: ${e.message}`);
  }
}

Next Steps

• Vanilla Python Client
• Advanced Usage