@atcute/xrpc-server#

a small web framework for handling XRPC operations.

quick start#

this framework relies on schemas generated by @atcute/lex-cli, you'd need to follow its quick start guide on how to set it up.

for this example, we'll define a very simple query operation, one that returns a message greeting the name that's provided to it:

// file: lexicons/com/example/greet.json
{
	"lexicon": 1,
	"id": "com.example.greet",
	"defs": {
		"main": {
			"type": "query",
			"parameters": {
				"type": "params",
				"required": ["name"],
				"properties": {
					"name": {
						"type": "string"
					}
				}
			},
			"output": {
				"encoding": "application/json",
				"schema": {
					"type": "object",
					"required": ["message"],
					"properties": {
						"message": {
							"type": "string"
						}
					}
				}
			}
		}
	}
}

now we can build a server using the TypeScript schemas:

// file: src/index.js
import { XRPCRouter, json } from '@atcute/xrpc-server';
import { cors } from '@atucte/xrpc-server/middlewares/cors';

import { ComExampleGreet } from './lexicons/index.js';

const router = new XRPCRouter({ middlewares: [cors()] });

router.add(ComExampleGreet.mainSchema, {
	async handler({ params: { name } }) {
		return json({ message: `hello ${name}!` });
	},
});

export default router;

on Deno, Bun or Cloudflare Workers, you can export the router directly and expect it to work out of the box.

but for Node.js, you'll need the @hono/node-server adapter as the router works with standard Web Request/Response:

// file: src/index.js
import { XRPCRouter } from '@atcute/xrpc-server';
import { serve } from '@hono/node-server';

const router = new XRPCRouter();

// ... handler code ...

serve(
	{
		fetch: router.fetch,
		port: 3000,
	},
	(info) => {
		console.log(`listening on port ${info.port}`);
	},
);