0Pricing
tRPC End-to-End Type Safe APIs · レッスン

サブスクリプション用WebSocketの設定

WebSocketサーバーを設定し、tRPCバックエンドと統合してリアルタイム通信を実現します。

「サブスクリプション用WebSocketの設定」はCoddyKit上の無料tRPC End-to-End Type Safe APIsレッスンです。 これはレッスン2/4です。 下記で完全なレッスンを無料で読むことができます。その後、ブラウザ内の組み込みコードエディタと24時間対応のAIチューターでハンズオン演習できます。 これはtRPC End-to-End Type Safe APIs学習パスの一部であり、ウェブとCoddyKitアプリ全体で進捗が同期されます。 tRPC End-to-End Type Safe APIsコースには全4レッスンが含まれています。

このレッスンの一部はまだ翻訳されておらず、英語で表示されています。

Real-time with WebSockets

When building modern web applications, real-time updates are often essential. Think of live chat, stock tickers, or notification systems.

Traditional HTTP requests are stateless and short-lived. WebSockets provide a persistent, bidirectional communication channel between a client and a server.

  • Persistent: The connection stays open, unlike HTTP.
  • Bidirectional: Both client and server can send messages at any time.
  • Efficient: Less overhead than constantly polling via HTTP.

Basic WebSocket Server Setup

Before integrating tRPC, let's understand how a standalone WebSocket server works. We'll use the popular ws library for Node.js.

First, install the necessary packages: npm install ws typescript ts-node

This basic server listens for connections and logs when clients connect or send messages.

import ws from 'ws';

const wss = new ws.Server({ port: 3001 });

wss.on('connection', (socket) => {
  console.log('Client connected to raw WS!');

  socket.on('message', (message) => {
    console.log(`Received: ${message}`);
    socket.send(`Echo: ${message}`);
  });

  socket.on('close', () => {
    console.log('Client disconnected from raw WS!');
  });

  socket.send('Welcome to the raw WS server!');
});

console.log('Raw WS server listening on ws://localhost:3001');

tRPC's WebSocket Adapter

tRPC needs a way to communicate over the WebSocket protocol. That's where @trpc/server/adapters/ws comes in.

This adapter allows your tRPC procedures to be exposed and handled by an existing WebSocket server (like the ws server we just saw).

Install it: npm install @trpc/server @trpc/server/adapters/ws

Preparing Your tRPC Router

For tRPC to handle subscriptions over WebSockets, you need a tRPC router and a context factory. This is similar to setting up an HTTP API, but for real-time communication.

Let's define a minimal tRPC setup. We'll add a simple subscription procedure next.

import { initTRPC } from '@trpc/server';

// Create a tRPC instance
const t = initTRPC.create();

// Define your application router
export const appRouter = t.router({
  // This will hold our subscription procedures
  healthcheck: t.procedure.query(() => 'ok'),
});

// Export the router's type for client-side usage
export type AppRouter = typeof appRouter;

// Context factory (can be empty for now)
export const createContext = () => ({});

Integrating tRPC with the WS Server

Now, let's combine our ws server with the tRPC router using the applyWSSHandler function from the adapter.

This function bridges your tRPC procedures to the WebSocket connection, making them available for real-time interaction.

  • wss: Your WebSocket server instance.
  • router: Your tRPC appRouter.
  • createContext: A function to create the tRPC context for each request.
import { applyWSSHandler } from '@trpc/server/adapters/ws';
import ws from 'ws';
import { appRouter, createContext } from './trpc'; // Assuming trpc.ts from previous scene

const wss = new ws.Server({ port: 3001 });

const handler = applyWSSHandler({
  wss,
  router: appRouter,
  createContext,
});

wss.on('connection', (socket) => {
  console.log(`tRPC WS client connected! Total: ${wss.clients.size}`);
  socket.once('close', () => {
    console.log(`tRPC WS client disconnected! Total: ${wss.clients.size}`);
  });
});

console.log('tRPC WS server listening on ws://localhost:3001');

// Optional: Handle graceful shutdown
process.on('SIGTERM', () => {
  console.log('SIGTERM received, closing WS server');
  handler.broadcastReconnectNotification(); // Notify clients to reconnect
  wss.close();
});

Creating a Simple Subscription

tRPC subscriptions use the observable pattern. An observable is a stream of data that a client can subscribe to, receiving updates over time.

Here, we create a basic onHello subscription that immediately sends a greeting and then cleans up.

// Inside your trpc.ts (update appRouter definition)
import { observable } from '@trpc/server/observable';

export const appRouter = t.router({
  healthcheck: t.procedure.query(() => 'ok'),
  onHello: t.procedure.subscription(() => {
    return observable<string>((emit) => {
      // Send a message immediately when subscribed
      emit.next('Hello from tRPC WebSocket!');

      // This function runs when the client unsubscribes
      return () => {
        console.log('Client unsubscribed from onHello');
      };
    });
  }),
});

Full tRPC WebSocket Server Code

Here's the complete server-side setup. You can save this as server.ts and run it with ts-node server.ts.

It combines the tRPC router with a subscription, the ws server, and the integration via applyWSSHandler.

import { initTRPC } from '@trpc/server';
import { applyWSSHandler } from '@trpc/server/adapters/ws';
import ws from 'ws';
import { observable } from '@trpc/server/observable';

// 1. tRPC Setup
const t = initTRPC.create();

const appRouter = t.router({
  healthcheck: t.procedure.query(() => 'ok'),
  onHello: t.procedure.subscription(() => {
    return observable<string>((emit) => {
      emit.next('Hello from tRPC WebSocket!');
      return () => { /* optional cleanup */ };
    });
  }),
});

export type AppRouter = typeof appRouter;
const createContext = () => ({});

// 2. WebSocket Server Setup
const wss = new ws.Server({ port: 3001 });

// 3. Integrate tRPC with WS Server
const handler = applyWSSHandler({
  wss,
  router: appRouter,
  createContext,
});

wss.on('connection', (socket) => {
  console.log(`Client connected! Total: ${wss.clients.size}`);
  socket.once('close', () => {
    console.log(`Client disconnected! Total: ${wss.clients.size}`);
  });
});

console.log('tRPC WebSocket Server listening on ws://localhost:3001');

// 4. Graceful shutdown
process.on('SIGTERM', () => {
  console.log('SIGTERM received, closing WS server');
  handler.broadcastReconnectNotification();
  wss.close();
});

Client-Side WebSocket Link

On the client-side, you need to configure your tRPC client to use the WebSocket connection. This is done with wsLink from @trpc/client/links/wsLink.

The wsLink tells your tRPC client where to connect for real-time data, distinct from your HTTP endpoint.

Install: npm install @trpc/client @trpc/react-query @tanstack/react-query

import { createWSClient, wsLink, httpBatchLink, createTRPCReact } from '@trpc/react-query';
import type { AppRouter } from '../server/server'; // Adjust path to your server's AppRouter

// Create a tRPC React client instance
export const trpc = createTRPCReact<AppRouter>();

// Create a WebSocket client instance
const wsClient = createWSClient({
  url: `ws://localhost:3001`,
});

export const trpcClient = trpc.createClient({
  links: [
    // Use the WebSocket link for subscriptions
    wsLink({
      client: wsClient,
    }),
    // Optionally, use HTTP for queries/mutations
    httpBatchLink({
      url: `http://localhost:3000/api/trpc`,
    }),
  ],
});

Consuming Subscriptions in Frontend

With the client configured, you can now use tRPC's useSubscription hook (if using React Query) to listen for real-time updates.

It works similarly to queries and mutations, but for continuous data streams, providing callbacks for new data and errors.

import React from 'react';
import { trpc } from './trpcClient'; // Assuming trpcClient.ts from previous scene

function MyComponent() {
  const [message, setMessage] = React.useState('Waiting for greeting...');

  // Subscribe to the 'onHello' procedure
  trpc.onHello.useSubscription(undefined, {
    onData(data) {
      // This callback fires whenever the server sends new data
      setMessage(data);
      console.log('Received subscription data:', data);
    },
    onError(err) {
      console.error('Subscription error:', err);
      setMessage(`Error: ${err.message}`);
    },
  });

  return (
    <div>
      <h1>Live Greeting:</h1>
      <p>{message}</p>
    </div>
  );
}

export default MyComponent;

Quick Check: WS Integration

You've learned how to set up a WebSocket server and integrate it with tRPC for real-time subscriptions. Which of the following are essential components or steps for this integration?

Recap: Setting Up WebSockets

You've successfully set up the foundation for real-time communication with tRPC!

  • We started with a basic WebSocket server using the ws library.
  • Then, we integrated our tRPC router with this server using @trpc/server/adapters/ws and applyWSSHandler.
  • We added a simple subscription procedure to our router using the observable pattern.
  • Finally, we configured the client with wsLink and saw how to consume subscriptions using useSubscription.

This robust setup allows your tRPC backend to push real-time updates directly to your frontend clients, leveraging type safety end-to-end.

よくある質問

「サブスクリプション用WebSocketの設定」レッスンは無料ですか？

はい。「サブスクリプション用WebSocketの設定」の完全なテキストはこのウェブで無料で読めます。インタラクティブに演習し（組み込みコードエディタと24時間対応のAIチューター）、tRPC End-to-End Type Safe APIsコースの残りをアンロックするには、CoddyKit PROにアップグレードしてください。 tRPC End-to-End Type Safe APIsコースには全4レッスンが含まれています。

「サブスクリプション用WebSocketの設定」で何を学びますか？

WebSocketサーバーを設定し、tRPCバックエンドと統合してリアルタイム通信を実現します。 ブラウザで直接実行するハンズオンコードでtRPC End-to-End Type Safe APIsを演習し、24時間対応のAIチューターがレッスンを進める中での質問に答えます。

tRPC End-to-End Type Safe APIsを始めるのに経験は必要ですか？

事前経験は必要ありません。CoddyKitのtRPC End-to-End Type Safe APIsは初級者から上級者向けに構成されているため、ここから始めるか最初から始めて、自分のペースで進むことができます。 これはレッスン2/4です。

「サブスクリプション用WebSocketの設定」レッスンにはどのくらい時間がかかりますか？

ほとんどのCoddyKitレッスンは約5～10分かかります。各レッスンはコンパクトでインタラクティブなので、着実に進歩し、ウェブとアプリ全体で正確に前回の場所から再開できます。

このtRPC End-to-End Type Safe APIsレッスンでコードを書いて実行できますか？

はい。すべてのtRPC End-to-End Type Safe APIsレッスンに組み込みコードエディタが含まれているため、ブラウザでリアルコードを書いて実行し、即座のAIフィードバックを取得できます。ローカル設定は不要です。

このコースのすべてのレッスン

  1. tRPCによるリアルタイム通信入門
  2. サブスクリプション用WebSocketの設定
  3. ライブデータサブスクリプションの実装
  4. 再接続とサブスクリプションのクリーンアップ
← tRPC End-to-End Type Safe APIsに戻る