This documentation is deprecated. It covers rspc 0.3.0, which is no longer maintained.
Vanilla Client
The vanilla client allows you to consume your API on the frontend. This client is the minimal core and it is recommended that you use the React or Solid integration for building application.
To get started first install the minimal runtime package.
npm i @rspc/clientNext you need to export the Typescript bindings from your rspc::Router by using either export_ts_bindings or export_ts.
let router = <rspc::Router>::new()
// This will automatically export the bindings to the `./ts` directory when you run build() in a non-release Rust build
.config(Config::new().export_ts_bindings("./bindings.rs"))
.build();Then you can use the @rspc/client package to consume your API.
import { createClient, FetchTransport } from "@rspc/client";
import type { Procedures } from "./ts/index"; // These were the bindings exported from your Rust code!
// You must provide the generated types as a generic and create a transport (in this example we are using HTTP Fetch) so that the client knows how to communicate with your API.
const client = createClient<Procedures>({
// Refer to the integration your using for the correct transport.
transport: new FetchTransport("http://localhost:4000/rspc"),
});
// Now use the client in your code!
const version = await client.query(["version"]); // The types will be inferred from your backend.
const userOne = await client.query(["getUser", 1]);
const userTwo = await client.mutation(["addUser", { name: "Monty Beaumont" }]);Transports
rspc has multiple different transports which can be used. These dictate how the frontend is able to talk with the backend.
Fetch Transport
Transport build on the standard Fetch API. This uses HTTP GET and POST requests under the hood.
rspc will generally use a GET request for queries and POST request for mutations however this isn't guaranteed.
import { createClient, FetchTransport } from "@rspc/client";
import type { Procedures } from "./bindings.ts"; // The bindings exported from your Rust code!
const client = createClient<Procedures>({
transport: new FetchTransport("http://localhost:4000/rspc"),
});Custom Fetch implementation
import { createClient, FetchTransport } from "@rspc/client";
import type { Procedures } from "./bindings.ts"; // The bindings exported from your Rust code!
const client = createClient<Procedures>({
transport: new FetchTransport(
"http://localhost:4000/rspc",
// Include Cookies for cross-origin requests
(input, init) => fetch(input, { ...init, credentials: "include" }),
),
});Fetch Authentication
Use a custom fetch function to attach credentials. This example assumes getAccessToken() returns your current application token:
const client = createClient<Procedures>({
transport: new FetchTransport("/rspc", (input, init) => {
const headers = new Headers(init?.headers);
const token = getAccessToken();
if (token) headers.set("Authorization", `Bearer ${token}`);
return fetch(input, { ...init, headers });
}),
});The server must verify the token before trusting it. For cookie sessions on another origin, use credentials: "include" as shown above and configure an explicit CORS origin with credentials support. Protect state-changing cookie-authenticated requests against CSRF.
Websocket Transport
This transport sends messages over a standard WebSocket connection after the HTTP upgrade.
import { createClient, WebsocketTransport } from "@rspc/client";
import type { Procedures } from "./bindings.ts"; // The bindings exported from your Rust code!
const client = createClient<Procedures>({
transport: new WebsocketTransport("ws://localhost:8080/rspc/ws"),
});Websocket Authentication
The browser WebSocket API does not support arbitrary authorization headers, and this transport has no custom handshake-header callback.
Use a same-origin cookie session if your server authenticates upgrade requests. Validate the origin and authorize each protected operation. Reconnect after a login or logout when the connection's credentials need to change. Use wss:// for an HTTPS site.
If your application needs bearer headers, use FetchTransport for queries and mutations or implement a transport with an explicit authentication exchange. Avoid long-lived tokens in WebSocket URLs.
Last updated on