Versión: 11.x

Adaptador Standalone

Traducción Beta No Oficial

Esta página fue traducida por PageTurner AI (beta). No está respaldada oficialmente por el proyecto. ¿Encontraste un error? Reportar problema →

El Adaptador Standalone de tRPC es la forma más sencilla de poner en marcha un nuevo proyecto. Es ideal para desarrollo local y entornos de producción basados en servidor. En esencia, es simplemente un envoltorio alrededor del servidor HTTP estándar de Node.js con las opciones habituales relacionadas con tRPC.

Si ya tienes un despliegue de API existente como Express, Fastify o Next.js donde quieras integrar tRPC, deberías consultar sus respectivos adaptadores. Igualmente, si prefieres alojar en entornos serverless o edge computing, tenemos adaptadores como AWS Lambda y Fetch que podrían ajustarse a tus necesidades.

Tampoco es raro, cuando el adaptador desplegado es difícil de ejecutar localmente, tener dos puntos de entrada en tu aplicación. Podrías usar el Adaptador Standalone para desarrollo local y un adaptador diferente en producción.

Aplicación de ejemplo

Description	Links
Standalone tRPC Server	StackBlitz Source
Standalone tRPC Server with CORS handling	StackBlitz Source

Configuración de un servidor tRPC Standalone

1. Implementa tu App Router

Implementa tu enrutador tRPC. Por ejemplo:

appRouter.ts
ts
import { initTRPC } from '@trpc/server';
import { z } from 'zod';
export const t = initTRPC.create();
export const appRouter = t.router({
  getUser: t.procedure.input(z.string()).query((opts) => {
    return { id: opts.input, name: 'Bilbo' };
  }),
  createUser: t.procedure
    .input(z.object({ name: z.string().min(5) }))
    .mutation(async (opts) => {
      // use your ORM of choice
      return await UserModel.create({
        data: opts.input,
      });
    }),
});
// export type definition of API
export type AppRouter = typeof appRouter;

appRouter.ts
ts
import { initTRPC } from '@trpc/server';
import { z } from 'zod';
export const t = initTRPC.create();
export const appRouter = t.router({
  getUser: t.procedure.input(z.string()).query((opts) => {
    return { id: opts.input, name: 'Bilbo' };
  }),
  createUser: t.procedure
    .input(z.object({ name: z.string().min(5) }))
    .mutation(async (opts) => {
      // use your ORM of choice
      return await UserModel.create({
        data: opts.input,
      });
    }),
});
// export type definition of API
export type AppRouter = typeof appRouter;

Para más información, consulta la guía de inicio rápido

2. Usa el adaptador Standalone

El adaptador Standalone ejecuta un servidor HTTP simple de Node.js.

server.ts
ts
import { initTRPC } from '@trpc/server';
import { createHTTPServer } from '@trpc/server/adapters/standalone';
import { appRouter } from './appRouter.ts';
createHTTPServer({
  router: appRouter,
  createContext() {
    console.log('context 3');
    return {};
  },
  // basePath: '/trpc/', // optional, defaults to '/'
}).listen(2022);

server.ts
ts
import { initTRPC } from '@trpc/server';
import { createHTTPServer } from '@trpc/server/adapters/standalone';
import { appRouter } from './appRouter.ts';
createHTTPServer({
  router: appRouter,
  createContext() {
    console.log('context 3');
    return {};
  },
  // basePath: '/trpc/', // optional, defaults to '/'
}).listen(2022);

Manejo de CORS y OPTIONS

Por defecto, el servidor standalone no responderá a solicitudes HTTP OPTIONS ni establecerá cabeceras CORS.

Si no estás en un entorno que gestione esto por ti (como durante desarrollo local), quizá necesites manejarlo manualmente.

1. Instala cors

Puedes agregar soporte tú mismo con el popular paquete cors

bash
yarn add cors
yarn add -D @types/cors

bash
yarn add cors
yarn add -D @types/cors

Para detalles completos sobre configuración, revisa la documentación

2. Configura el servidor Standalone

Este ejemplo simplemente abre CORS completamente, útil para desarrollo, pero en producción debes configurarlo de forma más restrictiva.

server.ts
ts
import { initTRPC } from '@trpc/server';
import { createHTTPServer } from '@trpc/server/adapters/standalone';
import cors from 'cors';
createHTTPServer({
  middleware: cors(),
  router: appRouter,
  createContext() {
    console.log('context 3');
    return {};
  },
}).listen(3333);

server.ts
ts
import { initTRPC } from '@trpc/server';
import { createHTTPServer } from '@trpc/server/adapters/standalone';
import cors from 'cors';
createHTTPServer({
  middleware: cors(),
  router: appRouter,
  createContext() {
    console.log('context 3');
    return {};
  },
}).listen(3333);

La opción middleware acepta cualquier función que se asemeje a un middleware connect/node.js, permitiendo usos más allá de manejar cors. Sin embargo, está diseñada como solución simple y no permite componer múltiples middlewares por sí sola. Para esto podrías:

Usar un adaptador alternativo con mejor soporte de middleware, como el adaptador Express
Emplear una solución para componer middlewares como connect
Extender el createHTTPHandler de Standalone con un servidor http personalizado (ver abajo)

Agregar un manejador a un servidor HTTP personalizado

createHTTPServer devuelve una instancia del http.Server incorporado en Node (https://nodejs.org/api/http.html#class-httpserver), dándote acceso a todas sus propiedades y APIs. Si createHTTPServer no satisface tus necesidades, también puedes usar la función createHTTPHandler del adaptador standalone para crear tu propio servidor HTTP. Por ejemplo:

server.ts
ts
import { createServer } from 'http';
import { initTRPC } from '@trpc/server';
import { createHTTPHandler } from '@trpc/server/adapters/standalone';
const handler = createHTTPHandler({
  router: appRouter,
  createContext() {
    return {};
  },
});
createServer((req, res) => {
  /**
   * Handle the request however you like,
   * just call the tRPC handler when you're ready
   */
  handler(req, res);
}).listen(3001);

server.ts
ts
import { createServer } from 'http';
import { initTRPC } from '@trpc/server';
import { createHTTPHandler } from '@trpc/server/adapters/standalone';
const handler = createHTTPHandler({
  router: appRouter,
  createContext() {
    return {};
  },
});
createServer((req, res) => {
  /**
   * Handle the request however you like,
   * just call the tRPC handler when you're ready
   */
  handler(req, res);
}).listen(3001);

Ruta base personalizada para manejar solicitudes bajo

El adaptador Standalone también soporta una opción basePath, que eliminará esta ruta base del inicio de la ruta de solicitud.

server.ts
ts
import { createServer } from 'http';
import { initTRPC } from '@trpc/server';
import { createHTTPHandler } from '@trpc/server/adapters/standalone';
const handler = createHTTPHandler({
  router: appRouter,
  basePath: '/trpc/',
});
createServer((req, res) => {
  if (req.url?.startsWith('/trpc/')) {
    return handler(req, res);
  }
  // [... insert your custom logic here ...]
  res.statusCode = 404;
  res.end('Not Found');
}).listen(3001);

server.ts
ts
import { createServer } from 'http';
import { initTRPC } from '@trpc/server';
import { createHTTPHandler } from '@trpc/server/adapters/standalone';
const handler = createHTTPHandler({
  router: appRouter,
  basePath: '/trpc/',
});
createServer((req, res) => {
  if (req.url?.startsWith('/trpc/')) {
    return handler(req, res);
  }
  // [... insert your custom logic here ...]
  res.statusCode = 404;
  res.end('Not Found');
}).listen(3001);

HTTP2

El adaptador Standalone también soporta HTTP/2.

server.ts
ts
import http2 from 'http2';
import { createHTTP2Handler } from '@trpc/server/adapters/standalone';
import { appRouter } from './_app.ts';
import { createContext } from './context.ts';
const handler = createHTTP2Handler({
  router: appRouter,
  createContext,
  // basePath: '/trpc/', // optional, defaults to '/'
});
const server = http2.createSecureServer(
  {
    key: '...',
    cert: '...',
  },
  (req, res) => {
    /**
     * Handle the request however you like,
     * just call the tRPC handler when you're ready
     */
    handler(req, res);
  },
);
server.listen(3001);

server.ts
ts
import http2 from 'http2';
import { createHTTP2Handler } from '@trpc/server/adapters/standalone';
import { appRouter } from './_app.ts';
import { createContext } from './context.ts';
const handler = createHTTP2Handler({
  router: appRouter,
  createContext,
  // basePath: '/trpc/', // optional, defaults to '/'
});
const server = http2.createSecureServer(
  {
    key: '...',
    cert: '...',
  },
  (req, res) => {
    /**
     * Handle the request however you like,
     * just call the tRPC handler when you're ready
     */
    handler(req, res);
  },
);
server.listen(3001);

context.ts
ts
import { CreateHTTP2ContextOptions } from '@trpc/server/adapters/standalone';
 
export async function createContext(opts: CreateHTTP2ContextOptions) {
  opts.req;
       
(property) req: http2.Http2ServerRequest
  opts.res;
       
(property) res: http2.Http2ServerResponse
 
  opts.info;
        
(property) info: TRPCRequestInfo
  return {};
}
 
export type Context = Awaited<ReturnType<typeof createContext>>;

context.ts
ts
import { CreateHTTP2ContextOptions } from '@trpc/server/adapters/standalone';
 
export async function createContext(opts: CreateHTTP2ContextOptions) {
  opts.req;
       
(property) req: http2.Http2ServerRequest
  opts.res;
       
(property) res: http2.Http2ServerResponse
 
  opts.info;
        
(property) info: TRPCRequestInfo
  return {};
}
 
export type Context = Awaited<ReturnType<typeof createContext>>;

Aplicación de ejemplo​

Configuración de un servidor tRPC Standalone​

1. Implementa tu App Router​

2. Usa el adaptador Standalone​

Manejo de CORS y OPTIONS​

1. Instala cors​

2. Configura el servidor Standalone​

Agregar un manejador a un servidor HTTP personalizado​

Ruta base personalizada para manejar solicitudes bajo​

HTTP2​