Version : 11.x

Adaptateur Standalone

Traduction Bêta Non Officielle

Cette page a été traduite par PageTurner AI (bêta). Non approuvée officiellement par le projet. Vous avez trouvé une erreur ? Signaler un problème →

L'adaptateur Standalone de tRPC est la méthode la plus simple pour démarrer un nouveau projet. Il est idéal pour le développement local et les environnements de production basés sur serveur. Fondamentalement, il s'agit simplement d'un wrapper autour du serveur HTTP Node.js standard avec les options habituelles liées à tRPC.

Si vous disposez déjà d'une API déployée comme Express, Fastify ou Next.js dans laquelle vous souhaitez intégrer tRPC, consultez leurs adaptateurs respectifs. De même, si vous préférez héberger sur du serverless ou du edge computing, nous proposons des adaptateurs comme AWS Lambda et Fetch qui pourraient correspondre à vos besoins.

Il est également courant, lorsque l'adaptateur de déploiement est difficile à exécuter localement, d'avoir deux points d'entrée dans votre application. Vous pouvez utiliser l'adaptateur Standalone pour le développement local et un autre adaptateur lors du déploiement.

Exemple d'application

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

Agents IA

Si vous utilisez un agent de codage IA, installez les compétences tRPC pour une meilleure génération de code :

bash
npx @tanstack/intent@latest install

bash
npx @tanstack/intent@latest install

Configuration d'un serveur tRPC Standalone

1. Implémentez votre routeur d'application

Implémentez votre routeur tRPC. Par exemple :

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 { id: '1', ...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 { id: '1', ...opts.input };
    }),
});
 
// export type definition of API
export type AppRouter = typeof appRouter;

Pour plus d'informations, vous pouvez consulter le guide de démarrage rapide

2. Utilisez l'adaptateur Standalone

L'adaptateur Standalone exécute un simple serveur HTTP Node.js.

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

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

Gestion du CORS & OPTIONS

Par défaut, le serveur standalone ne répondra pas aux requêtes HTTP OPTIONS et ne définira aucun en-tête CORS.

Si vous n'êtes pas dans un environnement qui peut gérer cela pour vous, comme lors du développement local, vous devrez peut-être le prendre en charge manuellement.

1. Installez cors

Vous pouvez ajouter vous-même la prise en charge avec le package populaire cors

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

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

Pour une documentation complète sur la configuration de ce package, consultez la documentation

2. Configurez le serveur Standalone

Cet exemple ouvre simplement le CORS à toutes les requêtes, ce qui est utile en développement, mais vous pouvez et devriez le configurer plus strictement en production.

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

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

L'option middleware acceptera toute fonction ressemblant à un middleware connect/node.js, elle peut donc être utilisée pour plus que la gestion du cors si vous le souhaitez. Cependant, elle est conçue comme une solution simple et ne permettra pas à elle seule de composer plusieurs middlewares. Si vous souhaitez le faire, vous pouvez :

Utiliser un autre adaptateur avec une meilleure prise en charge des middlewares, comme l'adaptateur Express
Utiliser une solution pour composer les middlewares comme connect
Étendre le createHTTPHandler Standalone avec un serveur HTTP personnalisé (voir ci-dessous)

Ajout d'un gestionnaire à un serveur HTTP personnalisé

createHTTPServer renvoie une instance du http.Server intégré à Node, ce qui signifie que vous avez accès à toutes ses propriétés et API. Cependant, si createHTTPServer ne suffit pas pour votre cas d'utilisation, vous pouvez également utiliser la fonction createHTTPHandler de l'adaptateur standalone pour créer votre propre serveur HTTP. Par exemple :

server.ts
ts
import { createServer } from 'http';
import { createHTTPHandler } from '@trpc/server/adapters/standalone';
import { appRouter } from './appRouter';
 
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 { createHTTPHandler } from '@trpc/server/adapters/standalone';
import { appRouter } from './appRouter';
 
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);

Chemin de base personnalisé pour le traitement des requêtes

L'adaptateur Standalone prend également en charge une option basePath, qui découpera ce chemin de base au début du chemin de la requête.

server.ts
ts
import { createServer } from 'http';
import { createHTTPHandler } from '@trpc/server/adapters/standalone';
import { appRouter } from './appRouter';
 
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 { createHTTPHandler } from '@trpc/server/adapters/standalone';
import { appRouter } from './appRouter';
 
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

L'adaptateur Standalone prend également en charge HTTP/2.

server.ts
ts
import http2 from 'http2';
import { createHTTP2Handler } from '@trpc/server/adapters/standalone';
import { appRouter } from './_app';
import { createContext } from './context';
 
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';
import { createContext } from './context';
 
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>>;

Exemple d'application​

Configuration d'un serveur tRPC Standalone​

1. Implémentez votre routeur d'application​

2. Utilisez l'adaptateur Standalone​

Gestion du CORS & OPTIONS​

1. Installez cors​

2. Configurez le serveur Standalone​

Ajout d'un gestionnaire à un serveur HTTP personnalisé​

Chemin de base personnalisé pour le traitement des requêtes​

HTTP2​