rspc

rspc is a high-performance, easy-to-use TRPC-like server framework for Rust. It allows you to define routers and attach procedures (queries and mutations) that can be easily consumed by clients, providing a type-safe bridge between Rust and frontend environments.

Note: rspc is no longer being maintained.

The rspc-binario crate is a proof of concept that demonstrates rspc's ability to support serialization libraries other than Serde. It allows you to use Binario for serialization and deserialization within your rspc setup.

CAUTION

This crate is a proof of concept. It is not intended for production use and will likely remain that way.

rspc provides several key capabilities for building type-safe APIs:

• Per Request Context: Allows you to attach data like database connections or authentication information to every request.
• Middleware: Supports intercepting requests with support for context switching.
• Merging Routers: Enables modular code organization by allowing you to define separate routers in different files and merge them into a single main router.

The Next.js example repository contains several files demonstrating different rspc integration patterns:

• Client Setup: src/rspc.ts demonstrates how to initialize the rspc client and generate React hooks.
• Global Configuration: pages/__app.tsx shows how to wrap your application with the necessary global provider.
• Data Fetching (Client-side):
  • pages/using-use-query.tsx demonstrates using the useQuery hook for fetching data.
  • pages/using-use-mutation.tsx demonstrates using the useMutation hook for performing side effects.
  • pages/using-use-subscription.tsx demonstrates using the useSubscription hook for real-time updates.
• Server-side Rendering (SSR): pages/using-ssp.tsx shows how to execute queries on the server side.

To run the Next.js example demonstrating rspc with @tanstack/react-query, follow these steps from the repository root:

1. Install dependencies using pnpm i.
2. Start the example projects using pnpm examples dev.

When using rspc with Tauri, you must manage permissions for the handle_rpc command. This command is responsible for processing incoming rspc requests from the frontend to the Rust backend.

To allow rspc requests to function, you must grant the rspc:allow-handle-rpc permission in your Tauri permission configuration.

To optimize your development experience when working with this template (Tauri, Rust, and TypeScript), the following VS Code extensions are recommended:

• VS Code
• Tauri extension
• rust-analyzer extension

A Procedure is the fundamental unit of work in rspc. It encapsulates a single server-side operation that a client can invoke.

Composition

A procedure is built from two main components:

1. Middleware: A sequence of functions that can intercept the request, modify the state, or perform side effects before/after the resolver.
2. Resolver: The core logic of the operation, which can be a query, mutation, or subscription.

Type Safety

Procedures are highly type-safe, leveraging Specta to ensure that input types, output types, and error types are correctly mapped and can be exported for client-side type generation. They support both standard Serde-compatible types and custom types via the ResolverInput and ResolverOutput traits.

The Invalidate<T> enum defines how a procedure should trigger invalidation when an event occurs. You can specify whether to do nothing, invalidate everything, or target specific inputs.

Variants:

• Invalidate::None: No invalidation occurs.
• Invalidate::Any: Triggers a global invalidation (implementation pending).
• Invalidate::One(T): Invalidates based on a single input of type T.
• Invalidate::Many(Vec<T>): Invalidates based on a collection of inputs of type T.

// Example of possible usage patterns
Invalidate::None
Invalidate::Any
Invalidate::One(input)
Invalidate::Many(vec![input1, input2])