Effect RPC (Experimental)

Alpha: This package is experimental and under active development. APIs may change at any time. Feedback and contributions are welcome!

[!NOTE] Documentation in Progress: We're actively working on comprehensive, easy-to-follow guides and walkthroughs. In the meantime, you can refer to the API documentation, where all exported members are thoroughly documented with JSDoc comments.

Effect RPC provides a type-safe, robust, and ergonomic way to call backend functions from your frontend—without ever writing fetch or worrying about error handling, dependency management, or response parsing. It is powered by Effect, enabling seamless full-stack development with strong type inference and composable effects.

Features

• End-to-end type safety: Types flow from backend to frontend, ensuring you never mismatch data or miss errors.
• No fetch required: Abstracts away HTTP, serialization, and network details.
• Automatic error handling: Errors are handled in a consistent, effectful way—no more try/catch everywhere.
• Composable: Built on Effect, so you can compose, layer, and manage dependencies naturally.
• Framework-agnostic: Designed for modern full-stack frameworks (Next.js, etc.), but not tied to any specific one.
• Batteries included: Use predefined hooks, services, properties and caller functions to reduce boilerplate

Installation

npm install effect-rpc
# or
pnpm add effect-rpc
# or
yarn add effect-rpc

Quick Example

1. Define the requests and router

// src/lib/rpc/hello/requests.ts
import * as S from "effect/Schema";

export class SayHelloFailedError extends S.TaggedError<SayHelloFailedError>("SayHelloFailedError", {
    message: S.String,
});

export class SayHelloReq extends S.TaggedRequest<SayHelloReq>("SayHelloReq")(
  "SayHelloReq",
  {
    payload: { name: S.NonEmptyString },
    success: S.NonEmptyString,
    failure: SayHelloFailedError,
  }
) {}

// ... and other requests

export const helloRouter = RpcGroup.make(
  Rpc.fromTaggedRequest(SayHelloReq),
  Rpc.fromTaggedRequest(SayByeReq).middleware(AuthMiddleware),
); // or .middleware(AuthMiddleware) here to add it to all. Just @effect/rpc

2. Define the implementation

// src/lib/rpc/hello/service.ts
import * as Effect from "effect/Effect";

export class HelloService extends Effect.Service<HelloService>()(
  "HelloService",
  {
    accessors: true,
    succeed: {
      sayHello: (name: string) => Effect.succeed(`Hello ${name}`),
      sayBye: (name: string) => Effect.succeed(`Bye ${name}`),
    },
  }
) {}

3. Create a runtime for the client

// src/lib/runtime.ts
import { createEffectRPC } from "effect-rpc";

export const AppRuntime = ManagedRuntime.make(
  Layer.mergeAll(
    createEffectRPC({ url: "http://localhost:3000/api/hello" })
    // AuthClientLive // if there's an auth middleware, for example
  )
);

3. Expose the router via an API route (Next.js example)

// src/app/api/hello/route.ts
import { helloRouter } from "@/lib/rpc/hello/requests";
import { HelloService } from "@/lib/rpc/hello/service";
import { createRPCHandler } from "effect-rpc";

const handler = createRPCHandler(
  helloRouter,
  {
    SayByeReq: ({ name }) => HelloService.sayBye(name),
    SayHelloReq: ({ name }) => HelloService.sayHello(name),
  },
  { serviceLayers: HelloService.Default }
);

export const POST = async (request: Request) => {
  try {
    return await handler(request);
  } catch (error) {
    console.error("Error in hello API:", error);
    return Response.json({ error: "Internal server error" }, { status: 500 });
  }
};

4. Call backend functions from the frontend

4.1 Using a hook in a client component

// src/components/greet-button.tsx
"use client";

import { helloRouter } from "@/lib/rpc/hello/requests";
import { AppRuntime } from "@/lib/runtime";
import { useRPCRequest } from "effect-rpc";
import { Effect } from "effect";

export function GreetUserButton() {
  const sayHello = useRPCRequest(helloRouter, "SayHelloReq");

  const greet = async () => {
    const greetPhraseProgram = sayHello({ name: "Ben" });
    greetPhraseProgram.pipe(
      Effect.catchTags({
        SayHelloFailedError: (error) =>
          Effect.succeed(`Error in SayHello: ${error.message}`),
      })
    );
    const greetPhrase = await AppRuntime.runPromise(greetPhraseProgram);
    alert(greetPhrase);
  };

  return <button onClick={greet}>Greet me!</button>;
}

4.2 In server actions

// src/lib/actions.ts
"use server";

import { makeServerRequest } from "effect-rpc";
import { helloRouter } from "../rpc/hello/requests";
import { AppRuntime } from "../runtime";

export async function greetUserServerSide(name: string): Promise<string> {
  const request = makeServerRequest(helloRouter, "SayHelloReq", { name });
  return AppRuntime.runPromise(request);
}

Example applications

• Next.js
• TanStack Start

Why Effect RPC?

• No more fetch boilerplate: Just call your backend functions as if they were local.
• Unified error handling: All errors are managed through Effect, so you can compose, catch, and recover as needed.
• Type-safe contracts: Your API surface is always in sync between client and server.
• Composable and testable: Use Effect's powerful features for dependency injection, testing, and more.
• Batteries included: Use predefined hooks, services, properties and caller functions to reduce boilerplate

Status & Roadmap

• Alpha: APIs are not stable. Expect breaking changes.
• Planned: More adapters (Express, Vercel, etc.), middleware support, advanced error mapping, and more.

Limitations

• Only supports JSON-serializable data for now.
• Not production-ready—use for experimentation and feedback.

Contributing

Contributions, issues, and feedback are welcome! Please open an issue or PR if you have suggestions or find bugs.

Made with ❤️ using Effect.