Prim+RPC is prerelease software. It may be unstable and functionality may change prior to full release.

Server Handlers

These are the currently supported handler plugins for Prim+RPC. For each Prim+RPC server instance you may choose one method handler and one callback handler (see Plugin Type in tables below). Remember that for each handler on the server you must also specify a compatible plugin on the client. For plugins/handlers to be compatible they must use the same type of transport (given in Transport Type in tables below).

Hono
Fastify
Express
WS
Nuxt / Nitro / H3
Next.js
Node / HTTP
Socket.io

Hono

For	Plugin Type	Transport Type	File Support
Hono	Method handler	HTTP	`File`

Prim+RPC supports Hono allowing it to be used from serverless environments easily.

You can configure Hono with Prim+RPC like so:


import { createPrimServer } from "@doseofted/prim-rpc"
import { createMethodHandler } from "@doseofted/prim-rpc-plugins/hono"
import { Hono } from "hono"
import module from "./my-example-module"
const app = new Hono()
const methodHandler = createMethodHandler({ app })
createPrimServer({ module, methodHandler })
export default app

You may also register the Hono middleware yourself by importing honoPrimRpc and using it directly with Hono. The .contextTransform option of the module can be used to set the this value inside of functions used with Prim+RPC.

Fastify

For	Plugin Type	Transport Type	File Support
Fastify	Method handler	HTTP	`File`

You can configure Fastify with Prim+RPC like so (note that the multipart plugin is optional and used for uploading files):


import { createPrimServer } from "@doseofted/prim-rpc"
import { createMethodHandler } from "@doseofted/prim-rpc-plugins/fastify"
import Fastify from "fastify"
import multipartPlugin from "@fastify/multipart"
import module from "./my-example-module"
const fastify = Fastify()
const methodHandler = createMethodHandler({
	fastify,
	multipartPlugin,
})
createPrimServer({ module, methodHandler })
fastify.listen({ port: 1234 })

You may use the .contextTransform option of createMethodHandler() to determine what values from Fastify are bound to the function's this context.

Express

For	Plugin Type	Transport Type	File Support
Express	Method handler	HTTP	`File`

You can configure Express with Prim+RPC like so (note that the multipart plugin is optional and used for uploading files):


import { createPrimServer } from "@doseofted/prim-rpc"
import { createMethodHandler } from "@doseofted/prim-rpc-plugins/express"
import express from "express"
import multipartPlugin from "multer"
import module from "./my-example-module"
const app = express()
const methodHandler = createMethodHandler({
	app,
	multipartPlugin,
})
createPrimServer({ module, methodHandler })
app.listen(1234)

You may use the .contextTransform option of createMethodHandler() to determine what values from Express are bound to the function's this context.

WS

For	Plugin Type	Transport Type	File Support
ws	Callback handler	WebSocket	None

You can configure ws with Prim+RPC like so:


import { createPrimServer } from "@doseofted/prim-rpc"
import { createCallbackHandler } from "@doseofted/prim-rpc-plugins/ws"
import { WebSocketServer } from "ws"
import module from "./my-example-module"
const wss = new WebSocketServer({ port: 1234 })
const callbackHandler = createCallbackHandler({ wss })
createPrimServer({ module, callbackHandler })

You may use the .contextTransform option of createCallbackHandler() to determine what values from ws are bound to the function's this context. The callback handler can be used with the method handler of your choice.

Nuxt / Nitro / H3

For	Plugin Type	Transport Type	File Support
Nuxt, Nitro, H3	Method handler	HTTP	`File`

Prim+RPC can be used with H3 and frameworks built upon H3 such as Nitro and Nuxt 3. Setup steps vary depending on which framework you are using.

You can configure H3 with Prim+RPC like so:


import { createPrimServer } from "@doseofted/prim-rpc"
import { createMethodHandler } from "@doseofted/prim-rpc-plugins/h3"
import { createApp, toNodeListener } from "h3"
import { createServer } from "node:http"
import module from "./my-example-module"
const app = createApp()
const server = createServer(toNodeListener(app))
const methodHandler = createMethodHandler({ app })
createPrimServer({ module, methodHandler })
server.listen(1234)

If you're not using H3 directly and are instead looking to use Prim+RPC with Nitro (Nuxt 3's server), you can configure a route for Prim+RPC like so (note that the filename is [...].ts, representing a catch-all route in Nitro):

api/[...].ts


import { createPrimServer } from "@doseofted/prim-rpc"
import { defineH3PrimHandler } from "@doseofted/prim-rpc-plugins/h3"
import module from "./my-example-module"
const prim = createPrimServer({ module, prefix: "/api/prim" })
export default defineH3PrimHandler({ prim })

On the client-side, you can use the Prim+RPC client with a compatible method plugin. Since the client could be used either server or client side, you may conditionally set the URL depending on the environment, like so:


import { createMethodPlugin } from "@doseofted/prim-rpc-plugins/browser"
const endpoint = typeof window === "undefined" ? "http://localhost:3000/prim" : "/prim"
const client = createPrimClient({
	endpoint,
	methodPlugin: createMethodPlugin(),
})

Next.js

For	Plugin Type	Transport Type	File Support
Next.js	Method handler	HTTP	`File`

Prim+RPC can be used with Next.js by defining a dedicated route. Currently, only the App Router is supported but Pages Router support is being considered. Next.js allows App/Page Routers to live in the same project.

You can configure the integration on the server like so (the [[...prim]] folder represents a catch-all route in Next.js):

app/prim/[[...prim]]/route.ts


import { createPrimServer } from "@doseofted/prim-rpc"
import { defineNextjsAppPrimHandler } from "@doseofted/prim-rpc-plugins/nextjs"
import module from "./my-example-module"
const prim = createPrimServer({ module, prefix: "/prim" })
export const { GET, POST } = defineNextjsAppPrimHandler({ prim })


import { createMethodPlugin } from "@doseofted/prim-rpc-plugins/browser"
const endpoint = typeof window === "undefined" ? "http://localhost:3000/prim" : "/prim"
const client = createPrimClient({
	endpoint,
	methodPlugin: createMethodPlugin(),
})

Node / HTTP

For	Plugin Type	Transport Type	File Support
Node	Method handler	HTTP	N/A

Unavailable (planned)

Socket.io

For	Plugin Type	Transport Type	File Support
Socket.io	Callback handler	Socket.io	N/A