@travelerdev/orpc-fastify

A Fastify plugin for integrating ORPC with Fastify servers. This package provides seamless integration between ORPC's type-safe RPC system and Fastify's high-performance web framework.

Features

• 🔌 Fastify Plugin: Easy integration with Fastify applications
• 🎯 Type-Safe RPC: Full TypeScript support with ORPC's type system
• 🚀 High Performance: Leverages Fastify's speed and ORPC's efficiency
• 🔧 Flexible Context: Customizable request context creation
• 📡 Standard Protocol: Compatible with ORPC's standard server implementation
• 🛡️ Strict GET Method: Built-in protection against unsafe GET requests

Installation

npm install @travelerdev/orpc-fastify

Peer Dependencies

This package requires the following peer dependencies:

• @orpc/server: ^1.8.8
• fastify: ^5.6.0

Quick Start

import Fastify from "fastify";
import { orpc } from "@travelerdev/orpc-fastify";
import { createRouter } from "@orpc/server";

// Create your ORPC router
const router = createRouter().query("hello", {
  input: z.object({ name: z.string() }),
  output: z.string(),
  handler: async ({ input }) => `Hello, ${input.name}!`,
});

// Create Fastify instance
const fastify = Fastify();

// Register the ORPC plugin
await fastify.register(orpc, {
  router,
  createContext: async ({ req }) => {
    // Create your request context here
    return {
      userId: req.headers["user-id"] as string,
      // ... other context properties
    };
  },
  prefix: "/api", // Optional: prefix for all routes
});

// Start the server
await fastify.listen({ port: 3000 });

API Reference

orpc Plugin

The main plugin function that registers ORPC with Fastify.

Options

interface FastifyORPCPluginOptions<R extends Router<any, Context>> {
  prefix?: `/${string}` | undefined; // Route prefix (optional)
  router: R; // ORPC router instance
  createContext: (args: {
    req: FastifyRequest;
  }) => Promise<Context | undefined>; // Context factory
  context?: Context | undefined; // Base context (optional)
  strictGetMethodPluginEnabled?: boolean; // Enable strict GET method protection (default: true)
}

Parameters

• router: Your ORPC router instance containing all your RPC procedures
• createContext: Function that creates request-specific context from Fastify request
• prefix: Optional URL prefix for all ORPC routes (e.g., /api)
• context: Optional base context that will be merged with request-specific context
• strictGetMethodPluginEnabled: Whether to enable strict GET method protection (default: true)

FastifyHandler

Internal class that handles the integration between Fastify and ORPC's standard server.

Advanced Usage

Custom Context Creation

await fastify.register(orpc, {
  router,
  createContext: async ({ req }) => {
    // Extract user information from request
    const token = req.headers.authorization?.replace("Bearer ", "");
    const user = await validateToken(token);

    return {
      user,
      requestId: req.id,
      timestamp: new Date(),
    };
  },
});

Base Context

await fastify.register(orpc, {
  router,
  context: {
    appVersion: "1.0.0",
    environment: process.env.NODE_ENV,
  },
  createContext: async ({ req }) => {
    return {
      userId: req.headers["user-id"] as string,
    };
  },
});

Custom Prefix

await fastify.register(orpc, {
  router,
  prefix: "/rpc/v1",
  createContext: async ({ req }) => ({}),
});

Related Packages

• @orpc/server - The core ORPC server implementation
• @orpc/standard-server - Standard server implementation
• fastify - Fast and low overhead web framework