0Pricing
tRPC End-to-End Type Safe APIs · Lesson

Implementing Live Data Subscriptions

Create tRPC subscription procedures to push real-time updates from the server to connected clients.

Implementing Live Data Subscriptions is a free tRPC End-to-End Type Safe APIs lesson on CoddyKit — lesson 3 of 4. You can read the complete lesson below for free — then practise it hands-on in the browser with a built-in code editor and a 24/7 AI tutor. It is part of the tRPC End-to-End Type Safe APIs learning path, one of 4 lessons in the course, and your progress syncs across the web and the CoddyKit app.

Real-time Data with Subscriptions

Welcome to the final lesson on tRPC real-time! We've learned about WebSockets, now let's build live data features.

Subscriptions in tRPC allow your server to push real-time updates to connected clients. Unlike queries (which pull data) or mutations (which modify data), subscriptions are push-based.

  • Queries: Client asks, server responds once.
  • Mutations: Client sends data, server performs action, responds once.
  • Subscriptions: Client asks once, server sends updates over time.

Defining Server Subscriptions

To create a subscription on your tRPC server, you use the createSubscription helper, similar to createQuery or createMutation.

A key difference is that a subscription procedure returns an observable. An observable is a stream of data that can emit multiple values over time.

Let's look at the basic structure.

The Observable Pattern

When defining a subscription, you'll use an observable pattern. This involves a function that receives an emit function and returns a cleanup function.

  • The emit function is what you call to send data to clients.
  • The cleanup function (returned by your subscription logic) runs when a client unsubscribes.

This allows you to manage resources like event listeners or intervals.

Server Code: Basic Live Counter

Here's a simple tRPC server-side subscription that emits a number every second. This number could represent anything, like a live user count.

import { router, publicProcedure } from './trpc';
import { observable } from '@trpc/server/observable';

export const appRouter = router({
  onUpdate: publicProcedure.subscription(() => {
    // This is where we create the observable
    return observable<number>((emit) => {
      let count = 0;
      const interval = setInterval(() => {
        count++;
        emit.next(count); // Push new data to clients
      }, 1000);

      // Return a cleanup function
      return () => {
        clearInterval(interval);
      };
    });
  }),
});

// This code is illustrative and not directly runnable
// without a full Node.js server setup.
// For context, 'router' and 'publicProcedure' would be
// initialized from '@trpc/server'.

Understanding the Server Flow

In the previous example:

  • publicProcedure.subscription(() => {...}) defines the subscription endpoint.
  • observable((emit) => {...}) creates a data stream that will send number types.
  • emit.next(count) is called repeatedly inside setInterval to push the current count to all subscribed clients.
  • The returned function () => { clearInterval(interval); } ensures the interval stops when a client disconnects or unsubscribes, preventing memory leaks.

Consuming Subscriptions on the Client

On the client-side, tRPC provides a convenient hook for consuming subscriptions, typically trpc.useSubscription if you're using React Query.

This hook works similarly to useQuery but maintains an open connection and updates your component whenever new data arrives from the server.

Client Code: React Component Example

Here's a React component that subscribes to our onUpdate procedure and displays the live counter. Notice how data updates automatically.

import React from 'react';

// Mock tRPC client for runnable example
const mockTRPCClient = {
  onUpdate: {
    subscribe: (opts) => {
      let count = 0;
      const interval = setInterval(() => {
        count++;
        opts.onData(count); // Simulate server pushing data
      }, 1000);
      return { // Return unsubscribe function
        unsubscribe: () => clearInterval(interval),
      };
    },
  },
};

// Mock useSubscription hook
const useSubscription = (path, input, { onData, onError }) => {
  React.useEffect(() => {
    const subscription = mockTRPCClient[path].subscribe({
      onData,
      onError,
    });
    return () => subscription.unsubscribe();
  }, [path, input, onData, onError]);
};

function LiveCounter() {
  const [currentCount, setCurrentCount] = React.useState(0);

  useSubscription(
    'onUpdate', // Path to your tRPC subscription
    undefined,  // No input for this subscription
    {
      onData(data) {
        setCurrentCount(data); // Update state with new data
      },
      onError(err) {
        console.error('Subscription error:', err);
      },
    }
  );

  return (
    <div>
      <h3>Live Counter:</h3>
      <p>Current value: <b>{currentCount}</b></p>
    </div>
  );
}

// This would be rendered by a framework like React.
// For runnable purposes, we can simulate a main entry point.
export default function Main() {
  return <LiveCounter />;
}

Subscriptions with Input

Just like queries and mutations, subscriptions can accept input. This is incredibly useful for filtering or customizing the data stream for each client.

For example, you might subscribe to updates for a specific productId or a particular chat roomName.

You'll define the input schema using Zod on the server and pass the input object on the client.

Code: Subscription with Input

Here's how you'd define a subscription that takes a topic string as input on the server, and how a client would use it.

/* --- SERVER-SIDE (Illustrative) --- */
import { z } from 'zod';
import { router, publicProcedure } from './trpc';
import { observable } from '@trpc/server/observable';

export const appRouterWithInput = router({
  onTopicUpdate: publicProcedure
    .input(z.object({ topic: z.string() })) // Define input schema
    .subscription(({ input }) => {
      return observable<string>((emit) => {
        // Simulate updates for a specific topic
        const interval = setInterval(() => {
          emit.next(`Update for '${input.topic}': ${Date.now()}`);
        }, 2000);
        return () => clearInterval(interval);
      });
    }),
});

/* --- CLIENT-SIDE (React Component) --- */
import React from 'react';

// Mock tRPC client for runnable example
const mockTRPCClientWithInput = {
  onTopicUpdate: {
    subscribe: (input, opts) => {
      const interval = setInterval(() => {
        opts.onData(`Update for '${input.topic}': ${Date.now()}`);
      }, 2000);
      return {
        unsubscribe: () => clearInterval(interval),
      };
    },
  },
};

// Mock useSubscription hook for runnable example
const useSubscriptionWithInput = (path, input, { onData, onError }) => {
  React.useEffect(() => {
    const subscription = mockTRPCClientWithInput[path].subscribe(
      input,
      { onData, onError }
    );
    return () => subscription.unsubscribe();
  }, [path, input, onData, onError]);
};

function TopicUpdates({ topic }) {
  const [latestUpdate, setLatestUpdate] = React.useState('');

  useSubscriptionWithInput(
    'onTopicUpdate', 
    { topic }, // Pass the input object
    {
      onData(data) {
        setLatestUpdate(data);
      },
      onError(err) {
        console.error('Subscription error:', err);
      },
    }
  );

  return (
    <div>
      <h4>Topic: {topic}</h4>
      <p>{latestUpdate}</p>
    </div>
  );
}

export default function Main() {
  return (
    <div>
      <TopicUpdates topic="news" />
      <TopicUpdates topic="sports" />
    </div>
  );
}

Best Practices for Subscriptions

When working with tRPC subscriptions, consider these best practices:

  • Cleanup: Always return a cleanup function from your observable to release resources (e.g., clear intervals, close database connections).
  • Error Handling: Implement onError callbacks on the client to gracefully handle subscription errors.
  • Rate Limiting: Be mindful of how frequently you emit data to avoid overwhelming clients or your server.
  • When to Use: Subscriptions are great for truly real-time data. For less critical updates, traditional queries with polling or client-side caching might be sufficient.
  • Authentication/Authorization: Use tRPC middleware to protect subscription procedures, ensuring only authorized users receive updates.

Quick Check: Subscription Basics

You've defined a tRPC subscription that emits a string every 5 seconds. Which part of the client-side useSubscription hook would you use to process each incoming string?

Recap: Live Data Subscriptions

In this lesson, you've learned to implement live data subscriptions with tRPC:

  • Server-side: Define subscription procedures using publicProcedure.subscription and return an observable.
  • Observable Logic: Use the emit.next() function to push data and return a cleanup function.
  • Client-side: Consume subscriptions using trpc.useSubscription, providing an onData callback to handle incoming real-time updates.
  • Input: Pass arguments to subscriptions for filtered or customized data streams.

Congratulations! You can now build powerful real-time features with tRPC's end-to-end type safety.

Frequently asked questions

Is the “Implementing Live Data Subscriptions” lesson free?

Yes — the full text of “Implementing Live Data Subscriptions” is free to read here on the web, and the tRPC End-to-End Type Safe APIs course includes 4 lessons in total. To practise it interactively (a built-in code editor and a 24/7 AI tutor) and unlock the rest of the tRPC End-to-End Type Safe APIs course, upgrade to CoddyKit PRO.

What will I learn in “Implementing Live Data Subscriptions”?

Create tRPC subscription procedures to push real-time updates from the server to connected clients. You practise tRPC End-to-End Type Safe APIs with hands-on code you run directly in the browser, and a 24/7 AI tutor answers your questions as you work through the lesson.

Do I need any experience to start tRPC End-to-End Type Safe APIs?

No prior experience is required. tRPC End-to-End Type Safe APIs on CoddyKit is structured for beginners through advanced learners; this is — lesson 3 of 4, so you can start here or from the beginning and move at your own pace.

How long does the “Implementing Live Data Subscriptions” lesson take?

Most CoddyKit lessons take about 5–10 minutes. Each one is bite-sized and interactive, so you make steady progress and pick up exactly where you left off across the web and the app.

Can I write and run code in this tRPC End-to-End Type Safe APIs lesson?

Yes. Every tRPC End-to-End Type Safe APIs lesson includes a built-in code editor, so you write and run real code right in your browser and get instant AI feedback — no local setup required.

All lessons in this course

  1. Introduction to Real-time with tRPC
  2. Setting Up WebSockets for Subscriptions
  3. Implementing Live Data Subscriptions
  4. Handling Reconnection and Subscription Cleanup
← Back to tRPC End-to-End Type Safe APIs