use-trpc v2.0.0-beta.1

👀 Features

• 🎻 Composable access to tRPC client, Queries, Mutations, and Subscriptions.
• ✔️ Configurable reactivity per query, mutation and subscription.
• 🗒️ Reactive Execution list for loading indicators.
• 🔃 Built-in tracking of reactive headers, procedure arguments and subscription arguments.
• 🔥 Automatic re-fetch and re-subscribe.
• 📦 Reactive data procedures and subscriptions.
• ☯️ Built with vue-demi to support Vue 2 and Vue 3.
• ⌨️ Built with TypeScript providing TypeSafe options.

📦 Install

npm i use-trpc

🎉 Basic Usage

By default reactive objects will automatically be tracked and trigger a new execution when they change

<script setup lang="ts">
  import { reactive, ref } from 'vue'

  import type { Router } from '../../path/to/trpc/router'
  import { useTRPC } from 'use-trpc'

  const { useQuery, useMutation } = useTRPC<Router>({
    url: import.meta.env.VITE_tRPC_URL
  })

  const id = ref(0)
  const { data } = useQuery('getUser', { args: reactive({ id }) })
</script>

<template>
  <pre>{{ data }}</pre>
  <button @click="id=10">GetUser</button>
</template>

👀 Configuration Examples

Reactive Headers

  // Shared composable for your app to get the active token
  const { token } = useToken() 
  const headers = reactive({
    Authorization: computed(() => `Bearer ${token.value}`),
  })

  // All procedures using this client will react and re-execute 
  // when the headers change
  const { useQuery, useMutation } = useTRPC<Router>({
    url: import.meta.env.VITE_tRPC_URL,
    headers,
  })

Reactive Arguments

  const id = ref(0)
  const { data } = useQuery('getUser', { args: reactive({ id }) })

  // Will trigger an execution of getUser with the id of 10
  id.value = 10

Opt-Out of Reactivity

When using a getter function for arguments reactive tracking will not be automatic. To Opt back into it you can set reactive to true and the getter function will be watched

  const id = ref(0)
  const { data } = useQuery('getUser', { args: () => reactive({ id }) })

  // Will not trigger an execution of getUser with the id of 10
  id.value = 10

Full HTTP Client Config

  const token = ref('')
  const headers = reactive({
    Authorization: computed(() => `Bearer ${token.value}`),
  })

  // Pass in a complete tRPC client proxy config for complete control
  const { client, isExecuting, executions, useQuery, useMutation } = useTRPC<Router>({
    headers,
    client: {
      links: [
        httpLink({
          url: import.meta.env.VITE_tRPC_URL,
          headers,
        }),
      ],
    },
  })

Simple HTTP + WebSocket Client

  const { useQuery, useSubscription, isExecuting, executions } = useTRPC<Router>({
    url: import.meta.env.VITE_tRPC_URL,
    wsUrl: import.meta.env.VITE_tRPC_WSURL,
  })

Enable the default tRPC Logger

  const { useQuery, useSubscription, isExecuting, executions } = useTRPC<Router>({
    url: import.meta.env.VITE_tRPC_URL,
    wsUrl: import.meta.env.VITE_tRPC_WSURL,
    // this can also be LoggerLinkOptions top configure a logger manually
    logger: true
  })

Full Query/Mutation Config

  const { data, execute, executing, immediatePromise, pause, paused, unpause } = useQuery(
    // path to the procedure
    'getUser',
    // useQuery configuration
    {
      // arguments for the procedure could also be `{id}`, `() => ({id})`, or `() => reactive({id})`
      args: reactive({ id }),
      immediate: true,
      initialData: { name: 'Bob' },
      msg: 'Loading User',
      // Full control of reactive tracking
      reactive: {
        args: true,
        headers: false
      }
    }
  )

Full Subscription Config

  const {
    data, 
    error, 
    subscribe, 
    unsubscribe, 
    subscribed, 
    state, 
    paused, 
    pause, 
    unpause,
  } = useSubscription(
    // path to the topic to subscribe to
    'uptime', 
    // useSubscription configuration
    {
      // input arguments for this subscription (can also be reactive, ref, or a getter function)
      args: 'auth-token', 
      initialData: { start: 0, uptime: 0 },
      immediate: true,
      onData(data) {
        console.log('onData', data)
      },
      onError(err) {
        console.log('onError', err)
      },
      onComplete() {
        console.log('subscription completed')
      },
      onStarted() {
        console.log('subscription started')
      },
      onStopped() {
        console.log('subscription stopped')
      },
    }
  )

⚙️ Configuration Details

useTRPC

Warning

When using the full client config with reactive headers you must also pass the reactive headers object, or function, into useTRPC as well. This allows for tracking of changes and re-execution of procedures

useQuery/useMutation

useSubscription

🎁 Return Details

useTRPC

useQuery/useMutation

useSubscription

💓 Thanks

This project is based on patterns from VueUse and of course relies on the amazing tRPC project

• tRPC
• VueUse