---
title: Usage
description: tRPC-Nuxt provides first class integration with tRPC.
---

# Usage

## Recommended file structure

Recommended but not enforced file structure. This is what you get when starting from [the examples](../main/example-apps.md).

```graphql
.
├── server
│   ├── api
│   │   └── trpc
│   │       └── [trpc].ts  # <-- tRPC HTTP handler
│   │   └── [..]
│   ├── trpc
│   │   ├── routers
│   │   │   ├── index.ts  # <-- main app router
│   │   │   ├── todo.ts  # <-- sub routers
│   │   │   └── [..]
│   │   ├── context.ts   # <-- create app context
│   │   └── trpc.ts      # <-- procedure helpers
├── plugins
│   ├── client.ts  # <-- tRPC Client as a plugin
└── [..]
```

## 1. Create a tRPC router

Initialize your tRPC backend using the `initTRPC` function and create your first router.

::code-group

```ts [server/trpc/trpc.ts]
import { initTRPC } from '@trpc/server'

// Avoid exporting the entire t-object since it's not very
// descriptive and can be confusing to newcomers used to t
// meaning translation in i18n libraries.
const t = initTRPC.create()

// Base router and procedure helpers
export const router = t.router
export const publicProcedure = t.procedure
```

```ts [server/trpc/routers/index.ts]
import { z } from 'zod'
import { publicProcedure, router } from '../trpc'

export const appRouter = router({
  hello: publicProcedure
    .input(
      z.object({
        text: z.string().nullish(),
      }),
    )
    .query(({ input }) => {
      return {
        greeting: `hello ${input?.text ?? 'world'}`,
      }
    }),
})

// export type definition of API
export type AppRouter = typeof appRouter
```

```ts [server/api/trpc/[trpc].ts]
import { createNuxtApiHandler } from 'trpc-nuxt'
import { appRouter } from '@/server/trpc/routers'

// export API handler
export default createNuxtApiHandler({
  router: appRouter,
  createContext: () => ({}),
})
```

::

::alert{type=info}
If you need to split your router into several subrouters, you can implement them in the `server/trpc/routers` directory and import and [merge them](https://trpc.io/docs/v10/merging-routers) to a single root `appRouter`.
::

## 2. Create tRPC client plugin

Create a strongly-typed plugin using your API's type signature.

```ts [plugins/client.ts]
import { httpBatchLink, createTRPCProxyClient } from '@trpc/client'
import type { AppRouter } from '@/server/trpc/routers'

export default defineNuxtPlugin(() => {
  const client = createTRPCProxyClient<AppRouter>({
    links: [
      httpBatchLink({
        /**
         * If you want to use SSR, you need to use the server's full URL
         * @link https://trpc.io/docs/ssr
         **/
        url: 'http://localhost:3000/api/trpc',
      }),
    ],
  })

  return {
    provide: {
      client,
    },
  }
})
```

## 3. Make API requests

```vue [pages/index.vue]
<script setup lang="ts">
const { $client } = useNuxtApp()

const data = await $client.hello.query({ text: 'client' })
</script>

<template>
  <p>{{data?.greeting }}</p>
</template>
```