server adapters/standalone

26 notes, read out of this brain and free to use. Each one was extracted from a source and is re-checked against its exam.

Standalone HTTP server setup with createHTTPServer

The standalone server adapter is created using createHTTPServer from @trpc/server/adapters/standalone. It accepts a router option containing the tRPC router. The createHTTPServer function returns a listen function that starts the server on the specified port. Example: createHTTPServer({ router: appRouter }).listen(3000) starts the API listening on port 3000.

createHTTPServer import path

The standalone HTTP server adapter is imported from @trpc/server/adapters/standalone.

tRPC deployment options

tRPC can run standalone or mounted as an endpoint on an existing REST API using adapters.

tRPC framework support

tRPC is framework agnostic. The tRPC community has built adapters for all of the most popular frameworks.

Backend framework options for tRPC

On the backend, there are adapters for a range of frameworks as well as vanilla Node.js.

Standalone adapter for serving tRPC

Use the standalone Node.js adapter from @trpc/server/adapters/standalone to serve a tRPC API. Call createHTTPServer with the router and call listen() with a port number to start the server.

Standalone server setup example

import { createHTTPServer } from '@trpc/server/adapters/standalone'; import { appRouter } from './appRouter'; const server = createHTTPServer({ router: appRouter, }); server.listen(3000);

Standalone adapter is simplest for local development

The Standalone Adapter is the simplest to use for local development or serverful infrastructure, as it can run a standard Node.js HTTP Server. It is recommended for getting started quickly when you have no existing HTTP Server to integrate with. Swapping adapters later is trivial if your needs change.

HTTP/2 server support in standalone adapter

The standalone adapter now supports HTTP/2 servers. Use createHTTP2Handler to create HTTP/2 servers and createHTTPServer to create HTTP/1 servers.

Custom basePath in standalone adapter

The standalone adapter now supports a basePath option that will slice the basePath from the beginning of the request path.

createHTTPServer basic setup

The createHTTPServer function from @trpc/server/adapters/standalone sets up a simple Node.js HTTP server. At minimum, pass the router and createContext function. The basePath option is optional and defaults to '/'.

createHTTPHandler for custom HTTP server

The createHTTPHandler function from @trpc/server/adapters/standalone creates an HTTP handler that can be used with a custom Node.js http.Server. It returns a function that accepts (req, res) parameters. This allows you to build your own HTTP server with custom logic while delegating tRPC requests to the handler.

basePath option strips prefix from request path

The basePath option in the Standalone adapter slices the basePath from the beginning of the request path. This is useful for handling requests under a specific prefix. For example, with basePath: '/trpc/', requests to /trpc/... will be routed to tRPC procedures.

Using basePath with createHTTPHandler

When using createHTTPHandler with a custom HTTP server, the basePath option can be used to strip a prefix from request paths. You must manually check if the request URL starts with the basePath before passing it to the handler.

Standalone adapter HTTP/2 support

The Standalone adapter supports HTTP/2 via the createHTTP2Handler function from @trpc/server/adapters/standalone. It works with http2.createSecureServer and requires a secure context with key and cert options.

createHTTP2Handler with HTTP/2

The createHTTP2Handler function sets up an HTTP/2 handler. It accepts router, createContext, and optional basePath. The createContext function receives CreateHTTP2ContextOptions which includes req, res, and info properties.

CreateHTTP2ContextOptions interface

The CreateHTTP2ContextOptions type from @trpc/server/adapters/standalone includes req, res, and info properties for use in the createContext function when setting up HTTP/2.

Create standalone HTTP server with tRPC

Use createHTTPServer from '@trpc/server/adapters/standalone' with { router: appRouter } config. Call server.listen(port) to start listening on the specified port.

Standalone adapter is a wrapper around Node.js HTTP Server

tRPC's Standalone Adapter is a wrapper around the standard Node.js HTTP Server with tRPC-related options. It is the simplest way to get a new project working and is ideal for local development and server-based production environments.

When to use Standalone adapter vs other adapters

Use the Standalone Adapter for new projects or local development. If you have an existing API deployment like Express, Fastify, or Next.js that you want to integrate tRPC into, use their respective adapters. For serverless or edge compute environments, use adapters like AWS Lambda or Fetch. It is common to use the Standalone Adapter for local development and a different adapter when deployed.

Basic setup of Standalone tRPC server with createHTTPServer

To set up a Standalone tRPC server, use the createHTTPServer function from '@trpc/server/adapters/standalone'. Pass an object with router (your tRPC router), and createContext function. Call .listen() on the returned server with a port number. Example: createHTTPServer({ router: appRouter, createContext() { return {}; } }).listen(2022);

Standalone middleware option limitations and alternatives

The middleware option in createHTTPServer is intended as a simple escape hatch and will not on its own allow composing multiple middlewares together. To compose multiple middlewares, either: use an alternate adapter with more comprehensive middleware support like Express adapter, use a solution like connect to compose middlewares, or extend the Standalone adapter using createHTTPHandler with a custom HTTP server.

Create custom HTTP server with createHTTPHandler

Use createHTTPHandler from '@trpc/server/adapters/standalone' to create a tRPC handler that you can integrate into your own HTTP server. Pass an object with router and createContext. Call the handler function with (req, res) to handle requests. Example: const handler = createHTTPHandler({ router: appRouter, createContext() { return {}; } }); createServer((req, res) => { handler(req, res); }).listen(3333);

How do you create a standalone HTTP server with tRPC

Use the createHTTPServer function from '@trpc/server/adapters/standalone', passing your router and a createContext function. Alternatively, use createHTTPHandler to get a handler function that you can integrate with Node.js's createServer for more control over the HTTP server configuration.

Standalone HTTP server with WebSocket support

A bare-minimum tRPC example demonstrates how to create a standalone HTTP server with WebSocket support using Vanilla TRPCClient in Node.js. This example shows the foundational setup for running tRPC without a framework like Next.js or Express.

Standalone server example repo location

The standalone HTTP server example is available in the tRPC repository at /examples/standalone-server. The example includes both a server.ts and client.ts file demonstrating the setup.

Give your agent this brain