# AGENTS.md — core-trpc

**Tag:** core-composition

Frontend tRPC platform providing the client and framework-specific providers (Next.js, TanStack). Bridges typed backend (`@repo/core-api`) to frontend applications. Tagged `core-composition` (not `core`) because it transitively reaches features through `core-api`'s `AppRouter` type.

## Responsibilities

- **Create tRPC React client** — `createTRPCReact<AppRouter>()` for use in React apps
- **Query client factory** — TanStack React Query setup per app
- **Framework-specific providers** — Next.js App Router provider + TanStack Start provider
- **No business logic** — purely framework integration

## Must NOT import

- Any feature package (`@repo/auth`, `@repo/blog`, etc.)
- Any app package
- `@repo/core-api`, `@repo/core-cms`, `@repo/core-ui`

## Public exports

From `package.json`:
- `.` — client + query client factory
- `./next` — Next.js App Router provider
- `./tanstack` — TanStack Start provider

Example usage:
```typescript
// In Next.js app
import { TrpcProvider } from "@repo/core-trpc/next";

// In TanStack Start app
import { TrpcProvider } from "@repo/core-trpc/tanstack";

// In client components
import { useTRPC } from "@repo/core-trpc";
const trpc = useTRPC();
```

## Test conventions

- No unit tests (provider layer)
- Verify at app boot: `pnpm dev --filter @repo/web-next` or `pnpm dev --filter @repo/web-tanstack` succeeds
- Verify client type safety: `pnpm typecheck` confirms `AppRouter` is imported and typed correctly

## Structure

```
src/
  client.ts                  # createTRPCReact<AppRouter>()
  query-client.ts            # makeQueryClient()
  providers/
    next-provider.tsx        # 'use client' provider for Next.js
    tanstack-provider.tsx    # Provider for TanStack Start
  index.ts                   # re-exports client + factories
```